Introducing the CaptivateController

It took me much much longer than I anticipated, but I am happy to announce the new CaptivateController utility. The CaptivateController is a JavaScript utility that helps you control Captivate SWFs using simple JavaScript commands. For example:

//Assuming your SWF is embedded using the ID "myID"
var myMovie = CaptivateController("myID");
myMovie.pause(); //Pauses the Captivate SWF
myMovie.mute(); //Mutes the Captivate SWF

For those of you familiar with the pipwerks.captivate.control utility, this CaptivateController is not a simple rehash of the original; it is a complete re-write that adds a number of extra features, including:

• Support for Captivate 2, Captivate 3, and Captivate 4 files
• Auto-detection for skins; you can write the exact same JavaScript whether your SWF uses a skin or not
• New query methods, including the ability to query a user-defined variable in a Captivate 4 file

The CaptivateController took a long time to develop because it deals with a number of inconsistencies between Captivate 2/3 SWFs and Captivate 4 SWFs, including the shift from using GetVariable to using Captivate 4’s proprietary cpGetValue (via ExternalInterface). It also handles inconsistencies with Flash Player in different browsers. Safari and Internet Explorer both provided their own small challenges.

There are still some inconsistencies that cannot be solved using JavaScript; for instance, Captivate 4 SWFs published using ActionScript 3 provide a richer set of system variables than Captivate 4 files published using ActionScript 2. I expected to have the same access to all system variables regardless of ActionScript version, but alas it was not meant to be.

Someday I hope to post a chart of which variables work when, but until then you can check out the Automated Test Suite, which illustrates which variables are available for each flavor of Captivate SWF.

Download

The CaptivateController weighs in at about 8kb and has been successfully tested in the following systems:

• Mac OS X (10.5): Firefox 3.0.10, Safari 3.2, Opera 9.6
• Mac OS X (10.6): Firefox 3.5.3, Safari 4.0.3
• Windows XP: Internet Explorer 6, Internet Explorer 8, Firefox 3.0.10
• Windows Vista: Internet Explorer 7

You can download the compressed version (8kb) here.

You can view the source version here (please do not hotlink).

Quickie documentation

I haven’t had the time to do a full write-up of the CaptivateController API, but the following information should be enough to get you started.

Don’t forget to check out the test suite. A list of Captivate Variables can be found on the Automated Test Suite and also in this blog post.

“Control” methods available in the API

Example:

//Assuming your SWF is embedded using the ID "myID"
var myMovie = CaptivateController("myID");
myMovie.pause(); //Pauses the Captivate SWF
myMovie.mute(); //Mutes the Captivate SWF

Commands can also be chained together, like so:

var myMovie = CaptivateController("myID");
myMovie.pause().mute(); //Pauses then mutes Captivate SWF

Query methods

The primary query technique is to use .query(“captivate_variable_name”). For example,

var myMovie = CaptivateController("myID");
//Retrieves the author's name, if available
var author = myMovie.query("cpInfoAuthor");

You can also use this method to query user-defined variables:

var myMovie = CaptivateController("myID");
 
//Retrieves the variable My_custom_variable_name, if available
var myUserDefinedvariable = myMovie.query("My_custom_variable_name");

I have created some additional query methods below. Some are designed to help avoid worrying which version of Captivate is being used (ie they work with both CP3 and CP4), and others provide data directly from the Flash SWF (not using CP variables).

You can also grab a reference to the SWF itself by using .swf. This is the equivalent of document.getElementById():

var myMovie = CaptivateController("myID");
myMovie.swf === document.getElementById("myID");

Does it work for you?

I’m planning on refining this controller utility over time. If you encounter any problems or have any suggestions for improvements/new features, please let me know by leaving a comment below.

DISCLAIMER: This controller is provided as-is. Use this controller at your own risk. I cannot be held responsible for any problems you may encounter while using the controller. kthxbai.

Related posts:

1. CaptivateController updated
2. Captivate 4 variables gone wild
3. Introducing the pipwerks Captivate Controller JavaScript utility
4. Control a Captivate SWF using JavaScript: The basics
5. Unpublished Captivate variables