Step 47 – LMSCommit()

The LMSCommit() API call is a little more complicated, but it bears a strong resemblence to the way that I handled LMSSetValue() in Rev 1 of the code – see this post for more details. What I’m going to do is to create a POST request and submit it to the server. But, where the old LMSSetValue() code only passed one variable value across, here I’m going to be passing all of the SCO-writeable data element values.

Here’s the JavaScript code that will be included in the api.php file:

function LMSCommit(dummyString) {

  // create request object
  var req = createRequest();

  // code to prevent caching
  var d = new Date();

  // set up request parameters - uses POST method
  req.open('POST','commit.php',false);

  // create a POST-formatted list of cached data elements 
  // include only SCO-writeable data elements
  var params = 'SCOInstanceID=&code='+d.getTime();
  params += "&data[cmi.core.lesson_location]="+urlencode(cache['cmi.core.lesson_location']);
  params += "&data[cmi.core.lesson_status]="+urlencode(cache['cmi.core.lesson_status']);
  params += "&data[cmi.core.exit]="+urlencode(cache['cmi.core.exit']);
  params += "&data[cmi.core.session_time]="+urlencode(cache['cmi.core.session_time']);
  params += "&data[cmi.core.score.raw]="+urlencode(cache['cmi.core.score.raw']);
  params += "&data[cmi.suspend_data]="+urlencode(cache['cmi.suspend_data']);

  // request headers
  req.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
  req.setRequestHeader("Content-length", params.length);
  req.setRequestHeader("Connection", "close");
  
  // submit to the server for processing
  req.send(params);

  // process returned data - error condition
  if (req.status != 200) {
    alert('Problem with AJAX Request in LMSCommit()');
    return "false";
  }

  // process returned data - OK
  else {
    return "true";
  }

}

Line-by-line:

• Line 4 – Sets up an AJAX request object.
   
• Line 7 – Creates a date object that I’ll use to make sure that the server treats this as a new request, and doesn’t cache it.
   
• Line 10 – I’m going to send this AJAX request to a new file called commit.php, and it’s going to include POST data rather than GET data because I don’t know whether or not it would be small enough to pass as GET data. As before, the third parameter is set to ‘false’ so the request is treated as synchronous – the JavaScript will wait for it to return a response.
   
• Lines 14 through 20 – I’m creating a JavaScript variable called ‘params’ which will hold (temporarily) all of the data that I’m going to transfer.
   
  • The first two variables – SCOInstanceID and code – should be familiar from my previous work.
     
  • The subsequent variables are transferring the data from the cache to commit.php as an associative array where the keys are the data element names. Note that I’m only transferring a subset of the data from the cache – these are the data elements that are SCO-writeable – see this post if you need a reminder.

   

• Lines 23 through 25 – I set up the request headers that will be sent to the LMS server to tell it that POST data is being submitted.
   
• Line 28 – I submit the request to the server along with the data to be stored in the LMS database.
   

Now to put together the code that will handle things at the server end of things. This is going to be a new file called commit.php.

<?php 

/*

VS SCORM - commit.php
Rev 1.0 - Thursday, November 19, 2009
Copyright (C) 2009, Addison Robson LLC

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, 
Boston, MA 02110-1301, USA.

*/

//  essential functions
require "subs.php";

//  read database login information and connect
require "config.php";
dbConnect();

// read SCOInstanceID
$SCOInstanceID = $_REQUEST['SCOInstanceID'] * 1;
$data = $_REQUEST['data'];
if (! is_array($data)) { $data = array($data); }

// iterate through the data elements
foreach ($data as $varname => $varvalue) {

  // save data to the 'scormvars' table
  writeElement($varname,$varvalue);

}

// return value to the calling program
print "true";

?>

Again, line-by-line:

• Lines 34 to 36 – Read the data that’s been passed to the script. Note that, in line 36, I make sure that the ‘data’ variable is handled as an array – probably superfluous, but may as well make sure!
   
• Lines 39 through 44 – I loop through the $data array and update the values stored in the LMS database using the writeElement() function that’s in subs.php.
   

And that’s it. Next time – LMSFinish() and some of the issues that arise from the student closing the window unexpectedly.