Adding SCORM code to an HTML file using the pipwerks SCORM wrapper

In my previous post, I briefly explained how to add SCORM code to an existing Flash file by using the pipwerks SCORM wrapper and SCORM ActionScript class.

Today, I’m going to explain how to add SCORM code to a plain HTML file. This example uses SCORM 1.2 syntax, but as I explain at the end of the tutorial, it’s really easy to edit the code to use SCORM 2004 syntax.

I certify that…

Let’s say you have a project where all you need to do is allow a user to confirm that they have completed a task, sort of like a digital signature. In e-learning, our clients often run into compliance issues where all they really need to do (or have time to do) is prove an employee was exposed to certain training materials.

For example:

“I, [name here], certify that I have read the materials presented to me.”
[Button: I agree]

This scenario is really easy to handle in any LMS with SCORM support. Let’s start by creating an HTML file containing a simple form.

Create the HTML

I’m using XHTML 1.0 Transitional in this example, but you can use XHTML 1.0 Strict or HTML 4 if you prefer… it doesn’t really matter.

<form id="myform" method="post">
  <fieldset>
  <legend>Please indicate your choice</legend>

I, [name here], certify that I have read the materials presented to me.
<input id="submit" name="submit" type="submit" value="Yes, I agree" />

  </fieldset>
</form>Code language: HTML, XML (xml)

Here is a functioning example of the plain HTML file (with CSS styling added).

Add some JavaScript to handle the form submission

JavaScript will be used to handle the form submission, SCORM communication, and text edits/feedback messages. Let’s start by adding a handler for the form submission.

Note: I always try to use progressive enhancement techniques in my web projects — avoid all inline scripting — which means we’ll use a window.onload event to apply our form submission code:

<script type="text/javascript">
window.onload = function (){
  //do something
};
</script>Code language: HTML, XML (xml)

In our simple example, we want to provide feedback when the form is submitted (something along the lines of “Your choice has been recorded”). We also want to disable the submit button when it’s clicked so that it doesn’t get submitted twice by mistake. We can kill two birds with one stone here by replacing the submission form with a custom feedback message. And it only takes one line of code in the initForm function! Sweet!

function initForm(){
    document.getElementById("myform").onsubmit = function (){
    this.innerHTML = "Thank you, your selection has been recorded. You may close this window.";
    return false; // This prevents the browser from trying to post the form results
  }
}Code language: JavaScript (javascript)

Here’s what we have so far: functioning example of the plain HTML file with JavaScript handling the form submission (CSS styling added).

SCORM it up

Okay, now that we have a functioning HTML file, lets’ add some SCORM code to it! The ‘course’ will need to perform the following tasks:

1. Connect to the LMS
2. Get the learner’s name (and add it to the HTML page)
3. Check for a previous completion
4. Set the course to “completed” if the user clicks the form submission button
5. disconnect from the LMS

Before we can start adding the SCORM code, we need to link to the pipwerks SCORM API wrapper (this example uses version 1.1.5).

Add the SCORM wrapper

Download the SCORM API wrapper, then add it to your page before the other JavaScript code.

<script src="SCORM_API_wrapper.js" type="text/javascript"></script>Code language: HTML, XML (xml)

Note: I’ve seen that some people don’t understand the difference between my pipwerks SCORM wrapper and the SCORM wrapper available from the ADL or other sources. The short version is: you only need the pipwerks wrapper! Do not include the other wrappers or you may run into errors; the pipwerks wrapper was designed to replace those wrappers while adding extra functionality and error-checking. As MacLeod used to say, “There can be only one…”. 😉

Add the SCORM code to your JavaScript

After linking to the wrapper, you’ll need to create two global variables (you can use object notation if you prefer, but I’ll keep it simple here to make it easier to follow).

var scorm = pipwerks.scorm;
var lmsConnected = false;Code language: JavaScript (javascript)

The variable scorm is a shortcut that helps reduce typing. If you didn’t use this shortcut, you’d need would need to use the full phrase <strong>pipwerks.scorm</strong>.xxx wherever you see <strong>scorm</strong>.xxx.

The variable lmsConnected is used to store a boolean (true/false) indicating whether or not we’re connected to the LMS.

Error handling

You should always include some kind of error handling in your code to let the user know what’s going on. For this example, I’m using a function that displays an alert, then closes the course window.

function handleError(msg){
   alert(msg);
   window.close();
}Code language: JavaScript (javascript)

Starting the course

Before we can make any calls to the LMS, we have to get the course connected! We’ll do this using a function named initCourse (feel free to use another name if you like).

function initCourse(){

   //scorm.init returns a boolean
   lmsConnected = scorm.init();

   //If the scorm.init function succeeded...
   if(lmsConnected){

      //Let's get the completion status to see if the course has already been completed
      var completionstatus = scorm.get("cmi.core.lesson_status");

      //If the course has already been completed...
      if(completionstatus == "completed" || completionstatus == "passed"){

         //...let's display a message and close the browser window
         handleError("You have already completed this course. You do not need to continue.");

      }

      //Now let's get the username from the LMS
      var learnername = scorm.get("cmi.core.student_name");

      //If the name was successfully retrieved...
      if(learnername){  

         //...let's display the username in a page element named "learnername"
         document.getElementById("learnername").innerHTML = learnername; //use the name in the form

      }

   //If the course couldn't connect to the LMS for some reason...
   } else {

      //... let's alert the user then close the window.
      handleError("Error: Course could not connect with the LMS");

   }

}Code language: JavaScript (javascript)

Edit the HTML

If you read through the code comments, you’ll see that we need to add an element named “learnername” to the page. I plan to display the username in the main sentence; here’s the edited HTML code:

<form id="myform" method="post">
  <fieldset>
  <legend>Please indicate your choice</legend>

I, <span id="learnername">[name here]</span>, certify that I have read the materials presented to me.
<input id="submit" name="submit" type="submit" value="Yes, I agree" />

  </fieldset>
</form>Code language: HTML, XML (xml)

The function initCourse will replace the text [name here] with the cmi.core.student_name from the LMS.

Add the completion code

Now that we’ve connected to the LMS, how do we set the course to complete? With a function named setComplete, of course! (Again, you can rename any of these functions of you prefer)

function setComplete(){

   //If the lmsConnection is active...
   if(lmsConnected){

      //... try setting the course status to "completed"
      var success = scorm.set("cmi.core.lesson_status", "completed");

      //If the course was successfully set to "completed"...
      if(success){

         //... disconnect from the LMS, we don't need to do anything else.
         scorm.quit();

      //If the course couldn't be set to completed for some reason...
      } else {

         //alert the user and close the course window
         handleError("Error: Course could not be set to complete!");

      }

   //If the course isn't connected to the LMS for some reason...
   } else {

      //alert the user and close the course window
      handleError("Error: Course is not connected to the LMS");

   }

}Code language: JavaScript (javascript)

Finishing touches

All that’s left now is adding the setComplete(); call to the form submission event (the course will not be set to complete unless the form is submitted), and adding the initCourse() call to the window.onload event:

function initForm(){

  document.getElementById("myform").onsubmit = function (){

    this.innerHTML = "Thank you, your selection has been recorded. You may close this window.";

    setComplete();

    return false; // This prevents the browser from trying to post the form results

  }

}

window.onload = function (){

  initCourse();
  initForm();

}Code language: JavaScript (javascript)

Here is the final product.

Prefer SCORM 2004 over SCORM 1.2?

This example uses the SCORM 1.2 calls cmi.core.lesson_status and cmi.core.student_name. If you prefer to use SCORM 2004, just change cmi.core.lesson_status to cmi.completion_status and cmi.core.student_name to cmi.learner_name. You should also remove the code snippet || completionstatus == "passed", since SCORM 2004 doesn’t use the term “passed”. The rest of the code remains the same!

Don’t forget the manifest!

LMSs require that SCORM courses include an imsmanifest.xml file. You will need to include one to get this example working on an LMS. The imsmanifest files vary greatly between SCORM 1.2 and SCORM 2004 (SCORM 2004 uses much more complex manifests).

Feedback appreciated

To borrow a line from A List Apart, “was it good for you, too?” Please let me know. Until next time…