Introducing SWFRightClick

Adobe Captivate currently ships with a 3rd-party JavaScript utility named RightClick.js, which enables the Captivate SWF to detect when a user right-clicks the SWF. While upgrading the Captivate publishing templates, I realized RightClick.js wasn’t built to work with SWFObject 2.x and suffered from a few shortcomings. I modified the Captivate template’s SWFObject code to get around the issue, but marked it down as something to revisit when I have the time.

Now, I’m happy to report I’ve created a replacement for the RightClick.js utility, creatively named SWFRightClick. It uses the same approach to handling right-clicks, but does it with a completely new codebase and a few extra goodies. SWFRightClick is compatible with every edition of SWFObject, and is free to use (MIT license).

Check it out on GitHub. I plan to fold it in to my Captivate publishing templates very soon.

Advertisements

Cleaning up Adobe Captivate’s SCORM Publishing Template, Part 5: Finishing up

In part one of this series, we published a simple Captivate course and examined its file structure. In part two, we cleaned up the HTML file and externalized all JavaScript. In part three, we cleaned up the JavaScript. In part four, we updated the SCORM code. In this installment, we will put the finishing touches on our code and move our files into Captivate’s publishing folder.

In the first four parts of this series, we were working with actual course files; these files need to be converted into template files. Once they’re set up as templates, you can just pop them into your Captivate templates folder and never worry about it again.

Let’s take a quick look at Captivate’s template folder structure:

I’m on a Mac, but the folder structure is the same on a Windows machine.

Our files were gathered from several locations:

  • The Manifest2004 folder contains all of the SCORM 2004 XSD files. We don’t need to edit any of these files.
  • The manifest2004.xml file is the SCORM 2004 imsmanifest.xml template. We don’t need to edit this file, though there are improvements that can be made.
  • The SCORM folder contains a 2004 subfolder, which in turn contains most of the HTML and JavaScript files we’ll need to edit.
  • The standard.js file contains the SWFObject 1.5 library.

Cleanup task #1: Refactor the code to eliminate the captivate.js file

In part two of this series we externalized JavaScript by creating a new file named captivate.js. This was useful while we refactored code, because it helped separate JavaScript from HTML and gave us a clearer picture of what we needed to work on. However, now that we’re trying to insert our edits into a Captivate publishing template, were stuck with the limitations of Captivate’s template and cannot add new files to the template — we can only edit existing files. We will therefore need to make a choice: where shall we place the contents of our new captivate.js file? In the HTML file, in scorm_support.js, or in standard.js?

There’s an easy answer: the HTML file.

Yes, this goes counter to my previous argument about externalizing the JavaScript, but we’re given little choice. The standard.js file is shared with 12 other templates; if you plan to use any of the other templates that ship with Captivate, we’ll need to leave this file alone (yes, that means leaving the SWFObject 1.5 library in your course even though we won’t be using it! Thankfully it has a very small footprint.).

scorm_support.js is a decent place to put our scripts, but it has one huge drawback: Captivate will not write anything to this file when publishing… and therein lies the problem!

When publishing a Captivate project using the SCORM 2004 template, the filename and dimensions are written to the HTML file (SCORM\2004\Default.htm). In fact, Default.htm is also renamed to match your project’s name. scorm_support.js and standard.js are never touched by Captivate; they are static files. In order for our modified template to work, we have to enable Captivate to write project details (project dimensions, filename, colors, etc.) to the HTML file.

The good news is that we significantly cleaned up the JavaScript, so captivate.js only contains a tiny amount of code.

Here are the modified HTML and scorm_support.js files after we get rid of captivate.js. There is much work to be done.

View the result of task #1

Cleanup task #2: Create a configuration object

Web apps normally use configuration objects — objects that contain data about how the app works. Since we know Captivate will write project details in the HTML, it makes sense to create a ‘config’ object.

Technically we could just use global variables, but an object dedicated to configuration information is a very clean way of working.

var CONFIG = {

};

So… what shall we put into this CONFIG object? Let’s start by looking in Default.htm to see what Captivate makes available to us. Anything prefixed with @ is a variable that gets written to the page by Captivate during the publishing process. A quick scan through the page reveals the following:

  • @MOVIETITLE (used in the HTML title element)
  • @MOVIENAME (the SWF filepath)
  • @IsRightClickFunctionalityRequired (an attribute placed in the HTML body element)
  • @SKINCOLOR (an attribute placed in the HTML body element)
  • @FlashPlayerVersion
  • @MOVIEWIDTH
  • @MOVIEHEIGHT
  • @WMODEVALUE (specifies what wmode should be used by Flash Player)

The whole IsRightClickFunctionalityRequired thing is problematic, we’ll get back to that later.

Here’s what we can put into our CONFIG object. I’m renaming a few of them for clarity and/or simplicity:

var CONFIG = {
    MOVIETITLE: "@MOVIETITLE",
    FILEPATH: "@MOVIENAME",
    BGCOLOR: "@SKINCOLOR",
    FPVERSION: "@FlashPlayerVersion",
    WIDTH: "@MOVIEWIDTH",
    HEIGHT: "@MOVIEHEIGHT",
    WMODE: "@WMODEVALUE"
};

We should also specify the name of the element that SWFObject will use to embed the SWF. Captivate normally names this file “CaptivateContent”, but it would be good to list it in the CONFIG object in case we ever need to edit it. (Spoiler: we will be editing it later.)

If you recall, we also have an if/else clause that displays a message to the learner if the SCORM API fails to load. We should place that message in our CONFIG object as well. This way you can quickly and easily reconfigure the message to suit your needs without digging through all of the template files.

var CONFIG = {
    TITLE: "@MOVIETITLE",
    FILEPATH: "@MOVIENAME",
    BGCOLOR: "@SKINCOLOR",
    FPVERSION: "@FlashPlayerVersion",
    WIDTH: "@MOVIEWIDTH",
    HEIGHT: "@MOVIEHEIGHT",
    WMODE: "@WMODEVALUE",
    TARGET: "CaptivateContent",
    NOSCORM: "Sorry, but the course is not available at this time (SCORM API not found). Please try again. If you continue to encounter problems, please contact the course administrator."
};

Cleanup task #3: Refactor the code using the CONFIG object

Now that our CONFIG object is ready to go, we need to replace all of the hard-coded values from our sample course with these configuration items. (Make a backup copy first!)

While we’re at it, we’ll place @MOVIETITLE into the title element, and @SKINCOLOR into our style element. Because of a quirk of the Captivate system, @SKINCOLOR can’t be followed by a semicolon in the CSS.

This will fail (semicolon after SKINCOLOR):

body { background: @SKINCOLOR; text-align: center; }

This will work (no semicolon):

body { text-align: center; background: @SKINCOLOR }

This configuration object enables us to move all other JavaScript out of the HTML and into scorm_support.js; the only JavaScript remaining on the HTML page are user-defined configuration items. Way cool. We have to be careful to reorder the script elements, so that the CONFIG object is created before scorm_support .js loads.

View the result of task #3

Cleanup task #4: Tidy up the HTML file a bit more

There are a few items that need attention in the HTML.

1. Quirks mode. Adobe placed two HTML comments above the doctype, which will trigger Internet Explorer to display the page in quirks mode. Since our page layout is so simple, quirks mode shouldn’t affect us, but it’s still a good practice to avoid placing comments above the doctype.

Current code:

<!-- Copyright [2008] Adobe Systems Incorporated.  All rights reserved -->
<!-- saved from url=(0013)about:internet -->

Before we move the comments, let’s stop and ask: are these comments even necessary? Are they useful? Well, the first comment is an Adobe copyright notice, which is questionable at best. What, exactly, is being copyrighted? The content of the page? Does that include your Captivate handiwork? Is the HTML being copyrighted? I’m not a lawyer, but I’m pretty sure you can’t copyright HTML markup. There is no clarity. Since I’ve competely obliterated what was provided by Adobe, anyway, I’m going to remove the copyright notice. Feel free to put it back if it makes you nervous, just place it *under* the doctype.

The second comment is what’s affectionately called “the mark of the web” (MOTW). Another reason to thank Microsoft. The short explanation is that MOTW enables you to view your Captivate file locally in Internet Explorer by forcing Internet Explorer to treat the page as if it were loading from the internet instead of your hard drive. If you intend to do any local testing with Internet Explorer, you should keep the MOTW in your template. I’m going to cut and paste the version recommended by Microsoft:


<!-- saved from url=(0014)about:internet -->

2. Remove page margins and padding. By default, all HTML pages have padding around the edges of the document, as well as a slight margin. Let’s remove all padding and margins to ensure the SWF comes up to the edge of the browser window. This will remove unsightly gaps when launching the course in the LMS’s popup window.

* { margin: 0; padding: 0; }

You may be asking: “What happens if the window is bigger than the SWF?” Currently, the SWF will be aligned to the top left corner. Centering the SWF is tricky, we’ll come back to that later.

3. Place the noscript block inside CaptivateContent. This isn’t necessary, but it’s a clean way of working. SWFObject will replace fallback content — content that only displays if something isn’t supported, such as JavaScript or Flash Player — with the SWF upon successful embed, leaving just the bare minimum markup in the HTML.

HTML before embed:


<div id="CaptivateContent"><noscript>
      This course requires JavaScript to be enabled in your browser. Please enable JavaScript, then relaunch the course.
      </noscript></div>

HTML after embed:

<div id="CaptivateContent"></div>

View the result of task #4

Cleanup task #5: Fix the right-click issue

As I mentioned earlier, Captivate has a variable named @IsRightClickFunctionalityRequired. This variable is located in the opening body tag.

Here’s how it looks in the HTML template:

If the Captivate SWF requires right-click functionality at any point, @IsRightClickFunctionalityRequired will add an onload event to the body element:

This is problematic for many reasons. First of all, adding an onload event directly to the body is considered a bad practice; inline JavaScript should be avoided whenever possible. It’s also a bad idea because the onload event is likely to overrule any window.onload events we might have in the external JavaScript.

After digging further into the IsRightClickFunctionalityRequired system, I have two additional concerns:

  1. Using this right-click functionality requires disabling accessibility in the Captivate preferences.
  2. The codebase for this functionality comes from a project named RightClick for Flash Player. It was developed before SWFObject 2.x existed, and therefore requires SWFObject 1.5 unless we make some modifications to our code.

Regarding the first concern, unfortunately, there’s nothing we can do about this in the template. It’s a choice you’ll need to make when authoring your Capivate projects. If you don’t like disabling Captivate’s accessibility features, please let Adobe know.

To understand the second concern, I must quickly explain a key difference bewteen SWFObject 1.x and SWFObject 2.x:

In SWFObject 1.5 — the version being used by Captivate — the SWF gets embedded inside the element you specify. For Captivate projects, the HTML winds up looking like this:

SWFObject JavaScript:

var so = new SWFObject("mymovie.swf", "Captivate", "550", "400", "10", "#CCCCCC");
//options here
so.write("CaptivateContent");

HTML before embed:

HTML after embed:

<div id="CaptivateContent"></div>

SWFObject 2.x changes this behavior. It replaces the target element, taking the ID of the element it replaces, unless a new ID is specified in the attributes object.

SWFObject JavaScript:

//SWFObject optional variables
var flashvars = {};
var params = {};
var attributes = { id: "Captivate" };
var callback = function (){ };

swfobject.embedSWF("mymovie.swf", 
                   "CaptivateContent", 
                   "550", 
                   "400", 
                   "10", 
                   false, 
                   flashvars, 
                   params, 
                   attributes, 
                   callback);

HTML before embed:

After embed:

To summarize: SWFObject 1.5 embeds the SWF inside your element, leaving the original element as a wrapper around your SWF, while SWFObject 2.x replaces the original element, leaving no wrapper.

The RightClick for Flash Player codebase requires the SWF to be located inside a wrapper element.

Normally, I’d edit the RightClick for Flash Player codebase to work with SWFObject 2. Unfortunately for me, it’s located in standard.js, which is used by all 13 Captivate publishing templates; if I update the code there, I’d need to replace ALL Captivate publishing templates. Not interested!

The solution is to write a function that creates a new wrapper div in our template before SWFObject is invoked. Of course, we only want to create this extra wrapper if right-click functionality is required.

Add a “rightClickRequired” property to our CONFIG object and populate it with the output of Captivate’s @IsRightClickFunctionalityRequired:

CONFIG.RIGHTCLICKENABLED = '@IsRightClickFunctionalityRequired';

When right-click functionality is required, Captivate will populate CONFIG.RIGHTCLICKENABLED for us:

//Note the use of single quotes
CONFIG.RIGHTCLICKENABLED = 'onload="RightClick.init();"  ';

When right-click functionality is not required, CONFIG.RIGHTCLICKENABLED will contain an empty string.

All we need to do is check to see if CONFIG.RIGHTCLICKENABLED is an empty string; if yes, create a wrapper div, embed the SWF, then initialize the right-click codebase. If no, just embed the SWF as usual.

View the result of task #5

Cleanup task #6: Center the SWF

Oh boy, this one is rough. Centering an element should be achievable through CSS alone, but unfortunately, we have some crazy restrictions and exceptions to deal with.

If you know the dimensions of the element, it’s easy to center it. We know the dimensions of our SWF — it’s provided via @MOVIEWIDTH and @MOVIEHEIGHT — so we’re on easy street, right? Wrong.

As I mentioned earlier when discussing the CSS code for the body background color, Captivate will not write a variable to the page if the variable name is adjoining any other text.

Consider the following CSS:

#Captivate { width: @MOVIEWIDTHpx; height: @MOVIEHEIGHTpx; }

It fails because “px” can’t be adjoining the @MOVIEWIDTH variable. Unfortunately CSS doesn’t allow us to place a space between the number value and the unit type. Assume @MOVIEWIDTH outputs 550 and @MOVIEHEIGHT outputs 400; if a space is provided between the value and the unit, the code is invalid and will fail:

#Captivate { width: 550 px; height: 400 px; }

Captivate is forcing us to use JavaScript to write the CSS values. Uuuuuugly, but there’s no getting around it.

Normally, if you’d like to center an element horizontally, you can just define the width (which we’ll have to do with JS), then set margin as follows:

#Captivate { display: block; margin: 0 auto; }

But to center an element vertically, we have more hoops to jump through, and it prevents us from being able to use the margin: 0 auto approach for horizontal centering. While there are some nice simple technquies out there for new browsers, they fail in older browsers. Most older sites use tables for layout because tables provides an easy and quick way to vertically center an element. But if you’ve read this entire series of posts, you can guess we’re not going to use tables — tables shouldn’t be used for layout! Period.

The most reliable CSS method is to use absolute positioning. This requires knowing the dimensions of the element, so we’ll be using a combination of CSS and JavaScript.

Added to the SWFObject callback function:

//Fix the centering for the SWF
CaptivateSWF.style.marginTop = "-" +(CONFIG.HEIGHT / 2) +"px";
CaptivateSWF.style.marginLeft = "-" +(CONFIG.WIDTH / 2) +"px";

Added to the HTML page’s CSS:

/* JavaScript is used to set pixel values for margin-left and margin-top */
#Captivate { position: absolute; top: 50%; left: 50%; }

We also set the height of body to 100%. Height is inherited from a parent element, so setting 50% height on an element won’t work in some browsers until you specify the parent element’s height.

View the result of task #6

Cleanup task #7: Final massaging!

We’ve done just about everything we can. The last step is to see if we can clean up our code to make it more tidy (and readable), then run it through some syntax checkers to look for bugs. I suggest JSHint.com, a fork of JSLint that doesn’t aim to hurt your feelings.

One change I’ll make is refactoring my CONFIG object to make it easier to read. While I prefer the original syntax (it compresses better, too), many n00bs prefer the more verbose style because they find it less confusing.

var CONFIG = {},
    flashvars = {},
    params = {},
    attributes = {};

CONFIG.TITLE = "@MOVIETITLE";
CONFIG.FILEPATH = "@MOVIENAME";
CONFIG.BGCOLOR = "@SKINCOLOR";
CONFIG.FPVERSION = "@FlashPlayerVersion";
CONFIG.WIDTH = "@MOVIEWIDTH";
CONFIG.HEIGHT = "@MOVIEHEIGHT";
CONFIG.WMODE = "@WMODEVALUE";
CONFIG.RIGHTCLICKENABLED = '@IsRightClickFunctionalityRequired';
CONFIG.TARGET = "Captivate";
CONFIG.NOSCORM = "Sorry, but the course is not available at this time (SCORM API not found). Please try again. If you continue to encounter problems, please contact the course administrator.";

//For SWFObject
params.bgcolor = CONFIG.BGCOLOR;
params.menu = "false";
attributes.name = CONFIG.TARGET;

While I’m cleaning, I’ll reduce the number of vars I introduced into scorm_support.js when adding new functions. This is also where we can do nitpicky stuff like replacing tabs with spaces and ensuring we have semicolons in the right places. Be sure to remove any alerts or console.log calls you may have added for debugging.

I think I’ll make one other change — add SWFObject 2.2 to standard.js. Yes, this means standard.js will contain both SWFObject 1.5 and 2.2, which is a bit odd. However it seems like a safe choice, since some institutions might not like loading SWFObject from a 3rd party CDN such as Google.

I’m also going to compress RightClick in standard.js to reduce file size. Be sure to make a backup copy if you’re following along.

View the result of task #7

Cleanup task #8: Move the files into the Captivate publishing folder

It’s been a long road, but we’re finally ready to make the jump! Let’s replace the existing template files.

You can grab the new code here.

First, make a backup of your entire publishing folder and put it somewhere safe!

Next, rename your HTML file to Default.htm and drag it into Templates\Publish\SCORM\2004\ (Original file was 11.8KB, new file is 1.7KB)

Now copy your scorm_support.js file to Templates\Publish\SCORM\2004\SCORM_support\ replacing the original file. (Original file was 6.7KB, new file is 7.4KB)

While you’re in your SCORM_support folder, go ahead and delete scorm_support.htm (590B) and scorm_support.swf (149B) — they won’t be used anymore.

Update: If you choose to delete these two files, you must edit Manifest2004.xml to reflect the change. Just remove the two lines that mention scorm_support.htm and scorm_support.swf (found at about line 108 in Manifest2004.xml).

Finally, go to Templates\Publish\ and replace standard.js with our updated copy. (Original file was 10KB, new file is 19KB)

Sweet: Even after adding SWFObject 2.2 to standard.js, we were able to shave about 1KB from the total file size! (29.25KB to 28.1KB)

Now restart Captivate and give it a try!

The next installment of the series will provide a quick summary as well as some additional options and considerations. Go to Part 6.

SCORM “Planets” Example Updated

Update 10/13/2011: I added more comments to the ActionScript code to help explain what each line of code does. I also added a Flash CS4 version of the FLA to the ZIP so more people can access the example.

My “Planets” example (How to Add Basic SCORM Code to a Flash Movie) has proven to be one of the most popular items on pipwerks.com. Unfortunately, it was designed as a quick example and had a bunch of flaws and shortcomings. It’s also about 3 years old and starting to show its age. Since people frequently contact me with questions — many of which were due to the flaws in the example — I decided to update the project.

The new Planets example has a bunch of fixes:

  • Full compliance with SCORM XSD requirements (it includes all those pesky XSD files that really don’t do anything but are required anyway).
  • Upgraded the pipwerks JavaScript wrapper to the latest version
  • Upgraded the pipwerks ActionScript 3 wrapper to the latest version
  • Upgraded SWFObject from 1.5 to 2.2
  • Changed the doctype and markup to HTML5
  • Added an unload handler to the JavaScript to ensure course progress is saved if the learner exits early
  • Added support for tracking progress across attempts using cmi.suspend_data
  • Completely rebuilt the FLA file to remove all timeline-based animation and scripts. Now uses a single ActionScript file, loaded on a single frame. All animations (fade transitions) are handled via ActionScript. This makes the file smaller and hopefully less confusing.
  • The SCORM code is clearly separated from the rest of the movie’s ActionScript; it’s in the same file, but not intermingled with other functions.

I haven’t decided if I’ll create a detailed tutorial to explain the updates; I’ve added a ton of comments to the ActionScript file, and hope it’s clear enough for others to follow.

Download the updated Planets example
The ZIP includes two FLA files: one in CS4 format, and the other in CS5.5. The code, movieclips, and graphic elements inside the FLAs are exactly the same.

Abstracting Your Course’s Tracking Code

An abstraction layer is a way of hiding complexities and maintaining cleanliness in your application. For example, if you want to save a file in your word processing application, you simply click “save”, while a whole host of actions is performed for you under-the-hood. In this example, you’re shielded from the complexity of your computer’s I/O operations by a graphical user interface.

When integrating tracking support (SCORM, AICC, etc,) into an an e-learning course, it’s a good idea to abstract as much of the tracking code as possible. For example, if you know your course is going to use SCORM 1.2, you might be tempted to write this:


//Assuming API is the SCORM API

//Display learner's name
var learner_name = API.LMSGetValue("cmi.core.student_name");

//Set course status to incomplete
API.LMSSetValue("cmi.core.lesson_status", "incomplete");

//Tell LMS to save whatever data we've sent
API.LMSCommit("");

This example hard-codes SCORM 1.2 into your course. If you ever decide to use SCORM 2004, you’d need to re-write whole chunks of your course. If you abstract the code by creating functions, you’re making it a little easier to update your code in the future:


//Assuming API is the SCORM API

function getLearnerName(){
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   API.LMSSetValue("cmi.core.lesson_status", "incomplete");
}

function save(){
   API.LMSCommit("");
}

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

Now that your tracking code is encapsulated in functions, it can be easily modified to include SCORM 2004 support:


//Assuming API is the SCORM API
//Checks for SCORM2004 mode, defaults to SCORM 1.2

function getLearnerName(){
   if(tracking_mode === "SCORM2004"){
      return API.GetValue("cmi.learner_name");
   }
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   if(tracking_mode === "SCORM2004"){
      API.SetValue("cmi.completion_status", "incomplete");
   } else {
      API.LMSSetValue("cmi.core.lesson_status", "incomplete");
   }
}

function save(){
   if(tracking_mode === "SCORM2004"){
      API.Commit("");
   } else {
      API.LMSCommit("");
   }
}


//Set tracking mode
var tracking_mode = "SCORM2004";

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

For e-learning courses, abstraction becomes even more powerful if you externalize your tracking-related functions. For example, you’d keep your tracking function invocations in your course code while placing the function definitions in a separate, easy-to-access file. This improves the separation of the tracking mechanism (SCORM, AICC, etc.) from the actual course logic.

Your course code:


//Set tracking mode
var tracking_mode = "SCORM2004";

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

An external JavaScript file containing the function definitions:


//Assuming API is the SCORM API
//Checks for SCORM2004 mode, defaults to SCORM 1.2

function getLearnerName(){
   if(tracking_mode === "SCORM2004"){
      return API.GetValue("cmi.learner_name");
   }
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   if(tracking_mode === "SCORM2004"){
      API.SetValue("cmi.completion_status", "incomplete");
   } else {
      API.LMSSetValue("cmi.core.lesson_status", "incomplete");
   }
}

function save(){
   if(tracking_mode === "SCORM2004"){
      API.Commit("");
   } else {
      API.LMSCommit("");
   }
}

Looking good, except for one thing… do you spot the big problem with this example? The tracking_mode variable is hard-coded in the course. A quick resolution is to dynamically set this variable via a querystring parameter when you load the course:


//Set tracking mode
//This is a quick and dirty example;
//there are better ways to handle querystrings
//Example: mycourse.html?tracking=SCORM2004
var tracking_mode = window.location.href.split("?tracking=")[1];

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

At this point, your course code is abstracted enough that it would be (relatively) trivial to add AICC support by modifying your tracking functions.

As you can see, the further we abstract, the cleaner your course’s code becomes. If you’re a Flash developer, use an additional level of abstraction — place your tracking functions in JavaScript and invoke them via ExternalInterface. While it may add a little up-front work, it will enable you to easily update your tracking code without needing to republish your FLAs.

Your course’s JavaScript:


//Assuming API is the SCORM API
//Checks for SCORM2004 mode, defaults to SCORM 1.2

//Set tracking mode
//This is a quick and dirty example;
//there are better ways to handle querystrings
//Example: mycourse.html?tracking=SCORM2004
var tracking_mode = window.location.href.split("?tracking=")[1];

function getLearnerName(){
   if(tracking_mode === "SCORM2004"){
      return API.GetValue("cmi.learner_name");
   }
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   if(tracking_mode === "SCORM2004"){
      API.SetValue("cmi.completion_status", "incomplete");
   } else {
      API.LMSSetValue("cmi.core.lesson_status", "incomplete");
   }
}

function save(){
   if(tracking_mode === "SCORM2004"){
      API.Commit("");
   } else {
      API.LMSCommit("");
   }
}

Your course’s FLA:


//Display learner's name
var learner_name:String = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

And here’s the glue: an abstraction layer meant to bridge the course FLA and the JavaScript tracking. Save as an external AS file (or a class/package if you’re feeling adventurous).


import flash.external.*;

function getLearnerName():String {
   return ExternalInterface.call("getLearnerName");
}

function setLessonIncomplete():void {
   ExternalInterface.call("setLessonIncomplete");
}

function save(){
   ExternalInterface.call("save");
}

In this example the tracking mode is set via JavaScript, and all of the tracking functionality is handled via JavaScript. If you ever needed to change from SCORM 1.2 to SCORM 2004 or AICC, you could handle it all via your JavaScript file and leave your Flash untouched. Easy breezy.

These are very simple examples, but hopefully they show the power of abstraction. Notice the last two examples have zero mention of SCORM in the course code itself. Sweet!

Of course, there is a downside to everything. As I mentioned in a thread on the E-Learning Technology and Development Google Group, abstracting like this takes time and can add quite a bit of work to your course development plan. If you know your course is a one-off that will only ever use one tracking method (such as SCORM 1.2), abstraction layers may be more effort than they’re worth. But if you’re not in a hurry, or know that your course will be around for a long time and will run on multiple LMSs, abstraction is a very good idea.

Abstraction and the pipwerks SCORM API Wrappers

What about the pipwerks SCORM API Wrappers? Well, they use some abstraction, but are not as abstracted as these examples. They can certainly help you on your way, but would need a bit of tweaking to reach this level of abstraction. I’m currently working on new SCORM wrappers that aim to support this level of abstraction. Stay tuned.

Complete List of Variables for Adobe Captivate 5

While updating my CaptivateController script I noticed there have been some changes to the Captivate variables available to Captivate developers. I figured I should document them for future reference.

Note that some variables available in CP3 and CP4 are no longer available. The following list should be exhaustive for CP5; variables for previous versions of Captivate have been purposely left off this list. I also purposely left off some publicly accessible (but useless) movieclips and objects.

While most people seem to focus on using Captivate variables natively within a Captivate project via the Variables menu or widgets, my focus has been figuring out how accessible/usable they are via JavaScript. Thus you may find small differences between my list and other people’s lists, and differing opinions regarding the usefulness of some variables and publicly accessible movieclips. Regardless, the items below should be accessible via every method: widgets, JavaScript, and the native Variables support in Adobe Captivate.

If you know of any variables that I missed, please leave a comment. Thanks!

Update: Kurt Melander has kindly converted this list to PDF format if you’d like to download or print it. Thanks, Kurt.

Variable Type Description

CPMovieType

[number] Informational variable. Indicates whether the queried SWF is a skin SWF (0) or the main content SWF (1).
CaptivateVersion [string] Informational variable. Indicates the version of Adobe Captivate that published the SWF
DoNotRegisterRightClickBecauseOfAggregator [boolean] Internal variable, no information available
LocalConnectionInUse [boolean] Internal variable, no information available
NoOfTOCEntries [number] Informational variable. Returns the number of items contained in the project’s Table of Contents

PlaybarProperties

[string]
in Chrome

[XML] in Firefox

Internal variable, no information available.

NOTE: This item is
:XML data type in AS3. Because browsers have different support for native XML data types, values returned from this variable should not be considered cross-browser. Use at your own risk.

__loadbase [string]

Informational variable. Returns project’s root file path.

NOTE: This value can only be obtained when the project uses an external skin.

contentHeight [number] Informational variable. Returns the height of the Captivate main SWF (in pixels)
contentLeft [number] Informational variable. Returns the distance of the Captivate main SWF from the leftmost edge of the project (in pixels).
contentSWF [string]

Informational variable. Returns the file name for the project’s main SWF.

NOTE: This value can only be obtained when the project uses an external skin.

contentTop [number] Informational variable. Returns the distance of the Captivate main SWF from the topmost edge of the project (in pixels).
contentWidth [number] Informational variable. Returns the width of the Captivate main SWF (in pixels)
cpAutoPlay [boolean] Informational variable. Indicates whether the project is set to auto-play.
cpCaptivateSkinSWF [boolean]

Informational variable. Indicates whether the SWF is a skin SWF or primary project SWF.

NOTE: This value can only be obtained when the project uses an external skin.

cpCmndCC [number] Command variable. Setting to 1 will enable captioning. Setting to 0 will disable captioning.
cpCmndFastForward [number] Command variable. Setting to 1 will fast-forward the movie (play the movie at a higher framerate). Setting to 0 will return the movie to the normal playback speed.
cpCmndGotoFrameAndResume [number]

Command variable. Will cause the movie to jump to the specified frame and resume playing (frame numbering begins at 0).

Note: frames are not the same as slides.

cpCmndGotoSlide [number]

Command variable. Will cause the movie to jump to the specified slide (slide numbering starts at 0).

Note: frames are not the same as slides.

cpCmndMute [boolean] Command variable. Setting to 1 will disable (mute) the audio. Setting to 0 will restore it to normal.
cpCmndNext [number] Command variable. Setting to 1 will cause the movie to jump to the next slide. Setting to 0 will do nothing.
cpCmndPlaybarMoved [boolean] Command variable. Internal variable. According to Captivate documentation, "Set to 1 if the playbar has moved."
cpCmndShowPlaybar [number] Command variable. Setting to 1 will cause the movie’s playbar to appear. Setting to 0 will make the palybar disappear.
cpCmndVolume [number] Command variable. Setting to a number will cause the volume to change. The volume ranges from 0 (muted) to 100 (maximum volume).
cpContentLoadStart [boolean]

Informational variable. Indicates whether the main project SWF has started.

NOTE: This value can only be obtained when the project uses an external skin.

cpContentLoaded [boolean]

Informational variable. Indicates whether the main project SWF has loaded.

NOTE: This value can only be obtained when the project uses an external skin.

cpContentPositioned Internal variable. No information available.
cpContentScaled Internal variable. No information available.
cpHasSkinSWF [boolean] Informational variable. Indicates whether the Captivate project uses an external skin.
cpInfoAuthor [string] Informational variable. Returns the project author’s name, as entered in the movie’s properties before publishing.
cpInfoCompany [string] Informational variable. Returns the project company’s name, as entered in the movie’s properties before publishing.
cpInfoCopyright [number] Informational variable. Returns the project’s copyright notice, as entered in the movie’s properties before publishing.
cpInfoCourseID [number] Informational variable. Returns the project’s course ID, as entered in the movie’s properties before publishing.
cpInfoCourseName [string] Informational variable. Returns the project’s course name, as entered in the movie’s properties before publishing.
cpInfoCurrentDate [string] Informational variable. Returns the day portion of the current date.
cpInfoCurrentDateString [string] Informational variable. Returns today’s date (US English format).
cpInfoCurrentDay [string] Informational variable. Returns number indicating day of week (1 = Sunday, 2 = Monday, etc.)
cpInfoCurrentHour [string] Informational variable. Returns the current hour (24 hour clock format).
cpInfoCurrentMinutes [string] Informational variable. Returns the minutes portion of the current time.
cpInfoCurrentMonth [string] Informational variable. Returns the month portion of the current date.
cpInfoCurrentSlide [number] Informational variable. Returns the current slide number. (Uses 1-based index)
cpInfoCurrentSlideLabel [string] Informational variable. Returns the slide label for the current slide, if available.
cpInfoCurrentSlideType [string] Informational variable. Returns the slide type for the current slide.
cpInfoCurrentTime [string] Informational variable. Returns the current time, including seconds (24 hour clock format).
cpInfoCurrentYear [string] Informational variable. Returns the year portion of the current date.
cpInfoDescription [string] Informational variable. Returns the project’s description, as entered in the movie’s properties before publishing.
cpInfoElapsedTimeMS [number] Informational variable. Returns the amount of time (in milliseconds) that has elapsed since the project began playing.
cpInfoEmail [string] Informational variable. Returns the project author’s e-mail address, as entered in the movie’s properties before publishing.
cpInfoEpochMS [number] Informational variable. Returns the current time elapsed (in milliseconds) since January 01, 1970.
cpInfoHasPlaybar [number] Informational variable. Indcates whether the Captivate movie has a playbar. 1=true, 0=false
cpInfoIsStandalone [number] Informational variable. Indicates whether Captivate project is en .exe or .app file (1) or standard SWF (0).
cpInfoLastVisitedSlide [number] Informational variable. Returns the last visited slide number. (Unlike cpInfoCurrentSlide, this variable uses 0-based index)
cpInfoPercentage [number] Informational variable. Returns the current score as a percentage (if available).
cpInfoPrevSlide [number] Informational variable. Returns the number of the slide before the current slide. (Uses 1-based index)
cpInfoProjectName [string] Informational variable. Returns the project’s name, as entered in the movie’s properties before publishing.
cpInfoWebsite [string] Informational variable. Returns the project’s web addess, as entered in the movie’s properties before publishing.
cpLockTOC [number] Command variable. Setting to 1 disables user interaction on the Table of Contents. Setting to 0 re-enables (unlocks) user interaction.
cpMovieHeight [number] Informational variable. Returns the height of the Captivate project, in pixels.
cpMovieWidth [number] Informational variable. Returns the width of the Captivate project, in pixels.
cpMovieXForEmbededPlaybar [number] Informational variable. Returns the x coordinate (left position) of the Captivate project’s toolbar, if available.
cpMovieXForTOC [number] Informational variable. Returns the x coordinate (left position) of the Captivate project’s Table of Contents movieclip, if available.
cpMovieYForEmbededPlaybar [number] Informational variable. Returns the y coordinate (top position) of the Captivate project’s toolbar, if available.
cpMovieYForTOC [number] Informational variable. Returns the y coordinate (top position) of the Captivate project’s Table of Contents movieclip, if available.
cpOrgSWFPath [string]

Informational variable. Provides the file name for the project’s main SWF. Appears to duplicate functionality of cpOrgSWFPath.

NOTE: This value can only be obtained when the project uses an external skin.

cpQuizInfoAnswerChoice [string] Informational variable. Returns the chosen answer for the quiz question.
cpQuizInfoAttempts [number] Informational variable. Returns the number of times the quiz has been attempted.
cpQuizInfoLastSlidePointScored [number] Informational variable. Returns the score for the last visited quiz slide.
cpQuizInfoMaxAttemptsOnCurrentQuestion [number] Informational variable. Returns the number of attempts allowed for this quiz question.
cpQuizInfoNoQuestionsPerQuiz Informational variable. No information available. Best guess: returns the number of questions in the quiz.
cpQuizInfoPassFail [number] Informational variable. Returns the result of the quiz: pass or fail.
cpQuizInfoPointsPerQuestionSlide [number] Informational variable. Returns the number of points for this quiz question.
cpQuizInfoPointsscored [number] Informational variable. Returns the total number of points scored in the project.
cpQuizInfoQuestionSlideTiming [number] Informational variable. Returns the time limit for the current question (in seconds).
cpQuizInfoQuestionSlideType [string] Informational variable. Returns the current question’s type (multiple-choice, true-false, likert, etc.).
cpQuizInfoQuizPassPercent [number] Informational variable. Returns the passing percentage for the quiz.
cpQuizInfoQuizPassPoints [number] Informational variable. Returns the passing points for the quiz.
cpQuizInfoTotalCorrectAnswers [number] Informational variable. Returns the number of correctly answered quiz questions.
cpQuizInfoTotalProjectPoints [number] Informational variable. Returns the total number of points for the project.
cpQuizInfoTotalQuestionsPerProject [number] Informational variable. Returns the total number of questions for the project.
cpQuizInfoTotalQuizPoints [number] Informational variable. Returns the total number of quiz points for the project.
cpQuizInfoTotalUnansweredQuestions [number] Informational variable. Returns the total number of unanswered questions for the project.
endSwfAction [number] Internal variable. No information available.
expired [boolean] Internal variable. No information available. Best guess: Boolean indicating whether time limit has elapsed.
hasProjectFadeOut [boolean] Internal variable. No information available. Best guess: Boolean indicating whether last slide in project is set to fade out.
inAutoPlayState [boolean] Internal variable. No information available. Best guess: Boolean indicating whether project is set to auto-play.
isCPMovie [boolean] Informational variable. Indicates whether the SWF is a Captivate SWF.
isContiniousModeRecording [number] Internal variable. No information available. (Yes, that’s how it was spelled in the code.)
isCustomizable [boolean]

Internal variable. No information available. Best guess: Indicates whether the skin is customizable.

NOTE: This value can only be obtained when the project uses an external skin.

isForceMuteAudio [boolean] Internal variable. No information available. Best guess: Indicates whether the audio was muted by the user.
isPlayBarBtnClicked [boolean] Internal variable. No information available. Best guess: Indicates whether a specific action was performed via clicking the playbar (such as muting audio).
isPreview [number] Internal variable. No information available. Best guess: Indicates whether the SWF is a preview SWF (used when previewing projects within the Captivate authoring environment).
isPreviewForAudioDialog [boolean] Internal variable. No information available. Best guess: Indicates whether the SWF is a preview SWF (used when previewing projects within the Captivate authoring environment).
isPreviewSkin [boolean] Internal variable. No information available. Best guess: Indicates whether the project SWF’s skin is a preview SWF (used when previewing projects within the Captivate authoring environment).
lmsString [string] Internal variable. No information available. Best guess: The text displayed when Captivate initializes an LMS connection (SCORM, AICC, etc.).
loadedFromAggregator [boolean] Internal variable. No information available. Best guess: Indicates whether the Captivate SWF was loaded as part of an aggregator project.
m_quizPoolColl [object] Internal variable. No information available. Best guess: Object containing question pool questions.
movieQuality [string] Internal variable. No information available. Best guess: Indicates quality setting of SWF playback.

movieXML

[string] in Chrome

[XML] in Firefox

Internal variable, no information available.

NOTE: This item is
:XML data type in AS3. Because browsers have different support for native XML data types, values returned from this variable should not be considered cross-browser. Use at your own risk.

needToMuteAudioForAggregator [boolean]

Internal variable. No information available.

NOTE: This value can only be obtained when the project uses an external skin.

passwordPresent [boolean] Internal variable. Indicates whether a password has been supplied.
pbcBtnTips [object] Internal variable. Alias for pbcBtnTips_ENU.
pbcBtnTips_ENU [object] Internal variable (array). Returns list of tooltips used by the playbar buttons.
playbarBarAlign [number]

Internal variable. No information available.

NOTE: This value can only be obtained when the project uses an external skin.

playbarHeight [number] Informational variable. Returns height of playbar, in pixels.
playbarPosition [number]

Internal variable. No information available.

NOTE: This value can only be obtained when the project uses an external skin.

rdIsInLivePreviewMode [boolean] Internal variable. No information available. Best guess: Indicates whether the SWF is a preview SWF (used when previewing projects within the Captivate authoring environment).
rdIsPreview [boolean] Internal variable. No information available. Best guess: Deprecated variable replaced by isPreview
rdIsPreviewInBrowser [boolean] Internal variable. No information available.
rdIsStandalone [boolean] Internal variable. No information available. Best guess: Deprecated variable replaced by cpInfoIsStandalone
rdcmndCC [number] Command variable (deprecated). Alias for cpCmndCC.
rdcmndExit [number] Command variable. According to Captivate documentation, "Exit the movie. Set to 1 to exit." Has never worked for me.
rdcmndGotoFrame [number] Command variable (deprecated). Alias for cpCmndGotoFrame.
rdcmndGotoFrameAndResume [number] Command variable (deprecated). Alias for cpCmndGotoFrameAndResume.
rdcmndGotoSlide [number] Command variable (deprecated). Alias for cpCmndGotoSlide.
rdcmndMute [boolean] Command variable (deprecated). Alias for cpCmndMute.
rdcmndNext [boolean] Command variable (deprecated). Alias for cpCmndNext.
rdcmndNextSlide [number] Command variable (deprecated). Alias for cpCmndNext.
rdcmndPause [number] Command variable. Setting to 1 will cause the movie to stop playing (pause). Setting to 0 will do nothing.
rdcmndPlaybarMoved [boolean] Command variable (deprecated). Alias for cpCmndPlaybarMoved.
rdcmndPrevious [number] Command variable. Setting to 1 will cause the movie to stop playing (pause). Setting to 0 will do nothing.
rdcmndResume [number] Command variable. Setting to 1 will cause the movie to go backwards to the previous slide. Setting to 0 will do nothing.
rdinfoCurrentFrame [number] Informational variable. Returns current frame number using 0-based index.
rdinfoCurrentSlide [number] Informational variable (deprecated). Alias for cpInfoCurrentSlide.
rdinfoCurrentSlideInProject [number] Informational variable. No information available. Best guess: Alias for cpInfoCurrentSlide.
rdinfoFPS [number] Informational variable. Returns the SWF’s frame rate (in seconds).
rdinfoFrameCount [number] Informational variable. Returns the number of frames in the SWF.
rdinfoHasPlaybar [boolean] Informational variable (deprecated). Alias for cpInfoHasPlaybar.
rdinfoSlideCount [number] Informational variable. Returns the number of slides in the Captivate movie.
rdinfoSlidesInProject [number] Informational variable. No information available. Best guess: An unused/deprecated variable.
rdinfocurrFrame [number] Informational variable. No information available. Best guess: Alias for rdinfoCurrentFrame.
skinHeight [number]

Internal variable. No information available.

NOTE: This value can only be obtained when the project uses an external skin.

skinWidth [number]

Internal variable. No information available.

NOTE: This value can only be obtained when the project uses an external skin.

swfCmtAutoPlay [boolean] Internal variable. No information available. Best guess: Indicates whether the SWF will auto-play when in commenting mode.
swfCommenting [boolean] Internal variable. No information available. Best guess: Indicates whether the SWF is in commenting mode.
tocInitDone [boolean] Internal variable. Indicates when the Table of Contents has finished initializing.
waitCount [number] Internal variable. Indicates how long the SWF has been waiting (used for internal timer-related functions).

CaptivateController Updated to Support Adobe Captivate 5

By popular demand, I’ve updated my CaptivateController to work with Adobe Captivate 5 (CP5). Since this is an open-source project, there’s no upgrade fee. (What? “Adobe” and “no upgrade fee” in the same paragraph?!) I kid, I kid… I’m a kidder.

As you may have heard, Adobe Captivate 5 is a complete re-write of the Adobe Captivate application. As such, there are a few significant changes under-the-hood. For example, Adobe Captivate 5 does not support ActionScript 2, and will only publish to ActionScript 3. The Captivate developers eliminated a few of the old system variables while adding a few new ones. Showing and hiding the playbar now works very reliably (yay!). Most notably, the developers added extra ExternalInterface support via the cpEIGetValue and cpEISetValue callback functions while eliminating the cpSetValue callback, which explains why the previous version of the CaptivateController didn’t work with CP5 SWFs.

As for the updated CaptivateController, it works the same as the previous version. Most of the changes were under-the-hood, so you shouldn’t need to edit any of your code, and should be able to drop this new version on top of your old one. No system restart required!

If you encounter any bugs, please let me know by posting in the comments. I’d also be happy to hear any success stories you may have.

SCORM Tip: Use an onunload handler

SCORM courses use JavaScript to send data to the LMS. This data then sits in the browser until the LMS writes it to the database (usually via AJAX or form posts). As previously discussed, invoking commit (save) will ensure the LMS actually writes this data to a database.

But what happens if the browser window containing your course is closed by the learner before the course finishes sending data to the LMS? If you’re not careful about how you’ve coded your course, you can lose some of the data. For example, if a learner completes the course and then immediately closes the window, the course might not have had enough time to tell the LMS about the completion, preventing the completion from appearing in the learner’s record.

It’s best to be proactive about this by setting up an event handler for the browser’s unload and onbeforeunload events. Whatever code you place in these events will execute when the browser is closed. In a SCORM course, you should place a commit (save) and terminate (quit) command in these events to ensure the SCORM data is properly persisted in the database and the session is properly terminated.

The code is pretty straightforward (this example uses SCORM 2004):


//Assuming API refers to your SCORM API
//and API_isActive returns a boolean indicating
//whether your API has already been terminated

var unloaded = false;
function unloadHandler(){
   if(!unloaded && API_isActive){
      API.SetValue("cmi.exit", "suspend"); //Set exit to whatever is needed
      API.Commit(""); //save all data that has already been sent
      API.Terminate(""); //close the SCORM API connection properly
      unloaded = true;
   }
}
window.onbeforeunload = unloadHandler;
window.onunload = unloadHandler;

Since some browsers support onbeforeunload and others don’t, we use the unloadHandler on both onbeforeunload and onunload, just to be safe. If a browser supports both of these events, the unloaded boolean ensures the scorm.quit function is not executed more than once.

If you’re using the pipwerks SCORM wrapper, your code will be even simpler, because the pipwerks wrapper automatically checks the API’s availability before performing any action. The wrapper also sets the cmi.exit/cmi.core.exit parameter for you.


var unloaded = false;
function unloadHandler(){
   if(!unloaded){
      scorm.save(); //save all data that has already been sent
      scorm.quit(); //close the SCORM API connection properly
      unloaded = true;
   }
}
window.onbeforeunload = unloadHandler;
window.onunload = unloadHandler;

SCORM Tip: Don’t forget to commit!

A number of people have recently asked me about the scorm.save() function in the pipwerks SCORM wrappers. What is it, and when should it be used?

The pipwerks scorm.save() function is a shortcut for SCORM’s Commit (SCORM 2004) and LMSCommit (SCORM 1.2) methods. Invoking commit in SCORM means you are explicitly instructing the LMS to persist the data you’ve sent. In other words, you’re telling the LMS to save your stuff!

When sending data from your course to the LMS, the data is traveling from the course window to the LMS via JavaScript and is stored in the browser. The SCORM spec gives LMSs the flexibility to decide when to transfer this data to the database. Some LMSs will not immediately write the data to the database because it can clog up the system; they prefer to queue up the data and send it in bunches. This explains why some courses will be successful in sending the data from the course to the LMS, but the LMS doesn’t seem to save the data. You didn’t tell it to! I know, I know, it seems daft, but it happens. So, to be safe, ensure your data gets saved by instructing the LMS to save the data.

Note that some LMSs will automatically commit at the end of a session, usually by detecting if the course window was closed (window.onunload) or if a certain CMI call was invoked, such as setting the completion status. However, you should never take your chances, and should design your SCO to commit regularly. Just be careful not to overdo it.

The rule of thumb is to invoke a commit (save()) if you use the pipwerks wrapper) after a significant chunk of data has been sent to the LMS, but not after each and every call:

NO (committing too frequently):


scorm.set("cmi.location", "some string indicating location");
scorm.save();
scorm.set("cmi.suspend_data", "your custom suspend_data string");
scorm.save();
scorm.set("cmi.score.raw", 80);
scorm.save();

NO (not committing enough):


scorm.set("cmi.location", "some string indicating location");
scorm.set("cmi.suspend_data", "your custom suspend_data string");
scorm.set("cmi.score.raw", 80);

YES (one commit after a short series of ‘set’ calls):


scorm.set("cmi.location", "some string indicating location");
scorm.set("cmi.suspend_data", "your custom suspend_data string");
scorm.set("cmi.score.raw", 80);
scorm.save();

What feature is missing from your e-learning development tool?

I have some simple questions I’d love to get feedback on.

I’m curious about what people are looking for in their e-learning authoring tools, specifically:

  1. What feature is your current tool missing that you would love to see implemented? Support for team collaboration? Support for themes or custom CSS styling? Support for language localization? A beer dispenser? Etc.
  2. What feature does someone else’s tool have that you’re jealous of?

For me? I wish the most popular tools (Captivate, Articulate, Lectora, etc.) would output cleaner HTML and JavaScript. I also wish there was less reliance on Flash and PowerPoint. But if you read my blog regularly, you probably already knew that!

Please post your opinion in the comments below, and please ask others to give their 2 cents. (You can also reply via twitter if you prefer)

I’m really looking forward to your comments. Thanks!