Tag: CaptivateController

This post has been updated to reflect changes to the CaptivateController since its initial release

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 as well as get/set Captivate variable values using simple JavaScript commands. For example:

//Assuming your SWF is embedded using the ID "Captivate"
var myMovie = CaptivateController("Captivate");
myMovie.pause(); //Pauses the Captivate SWF
var author_name = myMovie.get("cpInfoAuthor"); //Queries variables
myMovie.set("myCustomeCaptivateVariable", "myValue"); //Sets variable values

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, Captivate 4, and Captivate 5.x 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
• New set method for setting the value of a variable in Captivate 4+

The CaptivateController is intended to make your life easier — it deals with a number of inconsistencies so you don’t have to, including inconsistencies between Captivate 2/3 SWFs and Captivate 4 SWFs (there was a major shift under the hood, going 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 each 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. Captivate 5+ provides many m ore system variables than previous versions of Captivate.

Can check out the Automated Test Suite, which illustrates which variables are available for each flavor of Captivate SWF (has not been updated for Captivate 5+).

Download

The CaptivateController weighs in at about 6kb (compressed) and has been successfully tested in Chrome (Mac/Windows), Firefox (Mac/Windows), Safari (Mac), and Internet Explorer (Windows).

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, a list of Captivate 2-4 variables can be found here, and new CP5+ variables can be found here.

“Control” methods available in the API

Method	Notes
pause()
resume()
next()
previous()
rewindAndStop()
rewindAndPlay()
gotoSlideAndPlay(slidenumber)	Uses 1-based numbering: gotoSlideAndPlay(3) will take you to Slide 3. If you prefer Captivate’s built in zero-based numbering, use useZeroIndex(true) to change the numbering to a zero-based index.
gotoSlideAndStop(slidenumber)	Uses 1-based numbering: gotoSlideAndStop(3) will take you to Slide 3. If you prefer Captivate’s built in zero-based numbering, use useZeroIndex(true) to change the numbering to a zero-based index.
gotoFrameAndPlay(framenumber)
gotoFrameAndStop(framenumber)
volume(volumelevel)	Takes number, 0-100 Returns current volume level, 0-100 Volume only works in CP4+
mute()
unmute()
muteAndShowCaptions()
unmuteAndHideCaptions()
showCaptions()
hideCaptions()
showInfoBox()
hidePlaybar()	Doesn’t seem to work consistently via JavaScript
showPlaybar()	Doesn’t seem to work consistently via JavaScript
lockTOC()	Enables/disables user interaction on TOC Only works in CP4+
unlockTOC()	Enables/disables user interaction on TOC Only works in CP4+
exit()
useZeroIndex(boolean)	Specifies whether gotoSlideAndPlay and gotoSlideAndStop should use zero-based numbering (0 = slide 1). Set to true to use zero-based numbering. The default is false. Warning: This should only be invoked if you wish to use a zero-based index for gotoSlideAndPlay and gotoSlideAndStop.

Example:

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

Commands can also be chained together, like so:

var myMovie = CaptivateController("Captivate");
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("Captivate");
//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("Captivate");

//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).

Method	Notes
captivateVersion()	Returns major number, currently either 2 or 4 (Captivate 3 SWFs self-identify as CP2 SWFs, nothing can be done about this.)
asVersion()	Returns either 2 or 3
FPS()	Returns the frames per second of the SWF
hasSkinSWF()	Returns a boolean indicating whether the SWF is using a skin
hasTOC()	Returns a boolean indicating whether the movie has a Table of Contents
hasPlaybar()	Returns a boolean indicating whether the SWF has a playbar
width()	Returns a number indicating width in pixels
height()	Returns a number indicating height in pixels
volume()	Returns a number (0-100) indicating volume level. Note: volume only works in CP4+
percentLoaded()	Standard Flash SWF method, not specific to Captivate.
getname()	Returns the SWF’s ID. Standard Flash SWF method, not specific to Captivate.
geturl()	Returns the SWF’s URL. Standard Flash SWF method, not specific to Captivate.

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

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

Set method

There is a new set method (added November 2011) that enables developers to easily set the value of a Captivate variable using JavaScript. For example:

var myMovie = CaptivateController("Captivate");
myMovie.set("myCustomCaptivateVariable", "myValue");

Here is a test page demonstrating the set method.

Download

Download the CaptivateController The CaptivateController is now hosted on GitHub! The CaptivateController is licensed under an MIT license, and is free to use.

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.