The SCORM documentation and early SCORM examples have a heavy emphasis on framesets because SCORM 1.0 was released in 2000, only three years after HTML 4 (1997).

The authors and early adopters of SCORM used traditional framesets in their SCORM courses, because that’s simply how things were done at the time. 

I started building websites in 1994/95. Back then, if you wanted a sidebar containing site navigation on every page of your site, but didn’t want to copy and paste your markup into all of your site files, the easiest solution was to use a frameset.

Wordpress and content management systems didn’t exist yet, and most people were writing their markup by hand. Inline frames, commonly referred to as iframes, had been supported by Internet Explorer for a while, but had only been committed as a cross-browser standard via the HTML 4.01 spec in 1999. The original <frameset> was still very common. 

Learning management systems used traditional framesets to display SCORM packages, typically with the table of contents in a sidebar frame on the left, and the main content in a larger frame on the right. A header or footer might be included via a third frame.

Traditional framesets were clunky, suffered from accessibility issues, and gradually grew out of favor. As CSS and JavaScript support improved within browsers, web developers started to rely on dynamically loaded content (AJAX) and the occasional iframe. Eventually, traditional framesets developed a bad reputation and “frame” became a dirty word.

By 2014, the HTML5 spec made it official — the <frameset> element was deprecated. But the <iframe> lives on as part of the HTML5 spec, and is ubiquitous. Iframes power much of the dynamic web, including millions of widgets, including Twitter tweets, Instagram posts, YouTube embeds, and sign-up forms. The <iframe> is widely accepted part of the modern web, and is still a great option. 30 years after the invention of the iframe, every LMS still uses frames (most commonly an iframe) to display SCORM courses.

In e-learning, the iframe is typically configured to expand vertically and horizontally to fill the parent HTML document, obscuring the parent HTML from view, and giving the appearance of a single HTML file.

With this in mind, please don’t feel guilty for using an <iframe> in your SCORM courseware. Iframes are perfectly legit, support modern responsive design techniques, and are accessible (if built correctly). I can guarantee you that your LMS is loading your course into an <iframe>, anyway.

All of the code we've examined so far has been for single-page 'courses' (I use that term loosely). We’ve added our SCORM initialization code, and the course launches as expected. But what do we do if we’d like to add a second page? What happens if we add a ‘next’ button for the learner that automatically navigates from the first page to the second page? 

Believe it or not, navigating away from the first page would cause the course to stop dead in its tracks and cease reporting progress to the LMS. The SCORM API connection would be severed before the browser loads the second page into the browser window. The course session would be terminated, and any action taken on the second page would not be reported to the SCORM API.

Why?

Navigating away from the first page will cause the browser to unload all of the HTML, JavaScript, and other assets belonging to the first page. The browser will clear the table, metaphorically speaking, before serving the second page. Any assets that the two pages may have shared, such as scripts, stylesheets, or images, would have to be re-loaded.

Any JavaScript belonging to the first page, including the SCORM API connection, will stop running when the page unloads.The second page has no knowledge of the existence of the first page. 

Furthermore, the LMS likely monitors whether the first HTML file has unloaded, and will terminate the SCORM session because it knows the SCORM API connection has been severed.

You may be thinking “OK, so I just run LMSInitialize again. What’s the big deal?” Unfortunately, it’s not that simple — SCORM only allows LMSInitialize to run once per course launch, so you will not be able to re-initialize the session without closing the course window and relaunching via the LMS interface. 

The trick for SCORM courses is to never unload the HTML page that performs the initial handshake. This page will maintain the SCORM connection throughout the course session. You’d then use this single HTML page as a ‘parent’ for your course, and have all subsequent content load into this file dynamically. As you navigate the content in the course, the parent HTML remains intact, never breaking the SCORM API connection. 

There are several techniques for dynamically displaying content including toggling elements in a single monolithic HTML page, dynamically loading external content via AJAX, and using HTML framesets.

Monolithic HTML Pages

The simplest way to ensure your API connection remains active is to only use a single HTML page. For example, a slideshow system like Reveal.js places all content into <section> elements, then dynamically toggles their visibility as the visitor navigates the presentation. The page itself is never reloaded, which means the SCORM connection is never broken.

I will demonstrate how to use Reveal.js to build a course in an upcoming lesson.

Frames

The original technique recommended by the authors of SCORM is the traditional frameset, where an HTML file serves as a parent and loads HTML files as-needed into a child frames. In this scenario, the learner can navigate between child frames without unloading the parent frame. The child frames use JavaScript to send data to the parent frame, which keeps track of all course progress, and, in turn, reports the progress to the LMS via the SCORM API.

In my opinion, frames are still the best solution, though the HTML5 specification deprecates <frameset> in favor of <iframe>. 

AJAX and Reactive Frameworks

AJAX is a JavaScript technique utilizing a JavaScript’s xmlhttprequest (XHR) to load remote content. xmlhttprequest was created by Microsoft. It first appeared in Internet Explorer, and by 2005 had been adopted by other browsers. It would not be an overstatement to say AJAX completely transformed the World Wide Web and how we build websites today.

Prior to AJAX, if you wanted to change what is displayed on a page, such as a confirmation that a purchase was successful, you’d use server-side code to modify the HTML file, then completely reload the webpage to display the updated content. The AJAX technique uses JavaScript to fetch remote content (via XHR) then insert the content into the current HTML without requiring a page reload. 

The ability to alter page content without a page reload is why AJAX is a compelling option for building e-learning courses. If the page is never reloaded, the SCORM API connection remains intact.

A very famous example of an AJAX-based system is Google’s Gmail; the inbox you see when you open Gmail is one big HTML file. When you click a message in your inbox, xmlhttprequest is used to fetch the message’s content from the mail server, then JavaScript is used to merge the content into Gmail’s HTML and display the message on screen. All without requiring a page reload. 

When you close the message, JavaScript is used to hide the message and reveal your inbox again, without navigating away from the original HTML. You can view hundreds of messages without ever unloading the inbox you first saw when you opened Gmail.

AJAX is incredibly powerful, and is implemented in just about every major website you can think of. AJAX is best suited for systems that have clearly defined templates, such as Gmail’s inbox and message screens. 

Reactive Frameworks

Modern implementations of AJAX are reactive frameworks such as React, Angular, and Vue. These frameworks are AJAX on steroids, providing incredibly powerful features like reactive variables, reusable components, and the ability to quickly apply visual themes across the project.

As powerful as these systems are, they require a lot of time and careful planning to build a course framework and templates. Once you’ve built your templates, you're fairly locked in. In my experience, I found these kinds of templates less flexible over time, adding more technical debt and becoming less flexible as a result. For example, if I found or created a new JavaScript-powered interaction, I couldn't just plop it in the course – I would have to build an accompanying template, including sorting out the data fields and how to pass them to the interaction.

Having said that, a templated system utilizing reactive frameworks or traditional AJAX might be the perfect fit if your course will only need a handful of layouts or interactions!

These templatized systems can be very practical for large organizations who need to enforce specific standards across their courses. For example, templates allow a visual design team to lock the look and feel, branding, and any other visual style guidelines into place, ensuring a consistent, professional presentation regardless of who authors the course. Templates can enforce specific instructional pedagogies, which might be good if you have a very large team of instructional designers dispersed across the globe.

Templates are also clearly beneficial for e-learning development tool vendors, because a template can be throughly tested before release and easy supported afterward. 

For better or for worse, a template-based system essentially boils down to this: No flexibility means no surprises. You know ahead of time how it will look, you know ahead of time how it will behave, and you probably even know how long it will take to build a course because you’re basically just filling out forms. 

But this also underscores the price you pay when locking yourself into templates — a tremendous loss of agility when creating new layouts and interactions, and a ton of up-front work if you design your own template-based system.

If you've used a commercial e-learning development tool like Articulate Rise, you should be familiar with the limitations: What they give you is what you get, end of story. You are agreeing to be locked in to their system and their templates. 

Ultimately, this lack of flexibility is why I recommend using iframes instead of AJAX or reactive frameworks.

In iframe-based systems, your course is simply a collection of HTML pages. Each page is a blank canvas for whatever inspiration strikes you on a given day. Anything you can do with an HTML page can be done in your course. You are not locked in to a strict template system (though you can certainly make some templates to save yourself time in the future), and you can quickly try new ideas and iterate on them without having to worry about a complicated backend.

If you’ve set up your course’s tracking code to be reusable, such as what we’ve done in our prior examples, you can adapt almost any HTML-based interaction or content to work within your courses. And you can do it within minutes, not days or months.

A SCORM wrapper is JavaScript library that serves as an abstraction layer between the SCORM API and your course. If you’ve ever used jQuery, you can think of a SCORM wrapper’s relationship to the SCORM API as being very similar to jQuery’s relationship with a web browser’s DOM — the library’s goal is to help you write shorter, more concise JavaScript while helping you avoid some of the more painful parts of the underlying system. (The jQuery motto is “Write less, do more.”)

There are many SCORM wrappers available to you; they are not all created equal, and often handle tasks differently. For the purposes of this SCORM for Developers series, I will use the pipwerks SCORM wrapper, which I created back in 2008. While not perfect, it’s very reliable — it has been used in thousands of courses around the world over the fifteen years — and is open-source.

The ADL SCORM Wrapper

ADL provided a sample SCORM 1.2 wrapper when they released SCORM 1.2 in October 2001. Their wrapper became very popular and has been very widely used. I’m sure you can still find a number of courses using it. ADL’s wrapper was never intended to be THE wrapper — by their own admission, it was created as an example of what was possible. They expected others to extend and improve it. The comments in their wrapper mention “This is just one possible example for implementing the API guidelines for runtime communication between an LMS and executable content components. There are several other possible implementations.”

When I used the ADL wrapper in my courses, I found myself frustrated by writing the same chunks of SCORM code over and over, such as error-checking and exit handling. I figured if I could stick all of these items into a new wrapper, I would save myself a lot of time and typing. It would also allow me to clean up the JavaScript global space by eliminating all of the global variables used in the ADL wrapper.

If you don’t quite understand what all of that means, it’s okay, we’ll touch on these topics as we build our next sample course.

The pipwerks SCORM wrapper

The pipwerks SCORM wrapper was designed to make course development easier, so you can focus more on your course and less on the nit-picky SCORM stuff. The wrapper will help you with a number of tasks:

• Find the SCORM API and initialize the SCORM session
• Keep the global namespace clean
• Keep your code concise (shorter syntax, easier to understand naming conventions, helper functions, automation)
• Check for errors (e.g., was a SCORM call successful, or did the LMS return an error?)
• Keep your course abstracted (easily switch between SCORM 1.2 and SCORM 2004 if needed)

Find the SCORM API and initialize the SCORM session

If you’re working without a wrapper and writing your SCORM code directly, as we did in our example course at the beginning of this SCORM for Developers series, you would need to write quite a chunk of code. For starters, you’d need a function that locates the SCORM API. It can be tricky to find the SCORM API in some LMSs: Is it in the course window? The parent window? A frameset? A popup window? (Believe it or not, sometimes the answer is “all of the above.”)

Then once the API is found, you’d need to make it available to your course, then initialize the SCORM session using API.LMSInitialize. You’d need to verify whether or not the initialization was successful, and in most cases, will want to immediately set the course completion status to “incomplete”, then invoke LMSCommit.

I got tired of re-writing all of that code over and over, so I incorporated it into the pipwerks wrapper’s init routine. Now you can just write:

pipwerks.SCORM.init();

Keep the global namespace clean

Unlike other SCORM wrappers, all of the SCORM code in the pipwerks wrapper, including utility functions, getters/setters, debugging, etc., is contained under one global variable: pipwerks. This keeps the global namespace clean, which is important for preventing errors due to naming conflicts, and is a generally accepted best practice.

I will typically add a second global variable named scorm to my courses for convenience; it’s much easier to write scorm.doSomething() than pipwerks.SCORM.doSomething().

var scorm = pipwerks.SCORM;
//shorthand
scorm.init();
scorm.set("cmi.core.lesson_status", "completed");
scorm.save();

This means at most I have only added two global variables to the page, which is a nice, clean way of working.

Keep your code concise

You’ve already seen how the pipwerks wrapper can save you some typing, but it is also designed to make your course code more readable. Instead of typing

API.LMSSetValue("cmi.core.lesson_status", "completed");
API.LMSCommit("");

You can just type

scorm.set("cmi.core.lesson_status", "completed");
scorm.save();

As you can see, I use slightly different syntax; I shortened LMSSetValue to set, and changed LMSCommit to save, without requiring the nonsensical empty quotes required by LMSCommit(""). I find these terms easier to remember, easier to type, and easier to scan when I’m writing my course code.

Also, don’t forget the pipwerks wrapper has additional automation running under the hood; in the example above, the scorm.set function first checks to ensure the connection is active, then attempts to set the value. If the connection is not active, or if the call is not successful, the pipwerks wrapper will ping the LMS to get the error code and display the error in your JavaScript console.

Although the examples above look nearly identical, the second example is giving you much more functionality than the first example.

Check for errors

As mentioned in the SCORM API lesson, most SCORM functions return a value indicating whether or not they were successful. These values are booleans, but presented as the strings “true” and “false”. The pipwerks wrapper automatically converts them to authentic booleans, making them much easier to work with.

To illustrate, we can modify the example given above to verify whether the SCORM calls were successful:

var scorm = pipwerks.SCORM;
var wasSetSuccessful = scorm.set("cmi.core.lesson_status", "completed");
var wasSaveSuccessful = scorm.save();
if (wasSetSuccessful && wasSaveSuccessful) {
  alert("The LMS likes you!");
} else {
  alert("The LMS is not pleased.");
}

The wrapper also provides some preventative measures, such as automatically ensuring the SCORM session is still active before trying to get or set data.

When a SCORM API call is not successful, the LMS provides an error message providing more information. Retrieving this error code requires additional SCORM calls: LMSGetLastError and LMSGetErrorString. The pipwerks wrapper handles these via debug.getCode and debug.getInfo.

var scorm = pipwerks.SCORM;
var wasSetSuccessful = scorm.set("cmi.core.lesson_status", "completed");
var wasSaveSuccessful = scorm.save();
if (wasSetSuccessful && wasSaveSuccessful) {
  alert("The LMS likes you!");
} else {
  var message = scorm.debug.getInfo(scorm.debug.getCode());
  alert("The LMS is not pleased. It says " + message);
}

For convenience, all SCORM error messages are automatically displayed in the browser’s JavaScript console — no need to write a bazillion alert() or console.log() statements! If you prefer not to display error messages in the JavaScript console, you can easily turn them off with one line of JavaScript:

pipwerks.debug.isActive = false;

Keep your course abstracted

The pipwerks SCORM wrapper has one other nifty feature missing from most wrappers: it supports both SCORM 1.2 and 2004. SCORM 2004 uses slightly different syntax than SCORM 1.2, such as API.Initialize instead of API.LMSInitialize and API.Terminate instead of API.LMSFinish. The pipwerks wrapper will look to see which version of SCORM is being used by the course, and will select the appropriate syntax.

If you ever decide to convert a course from SCORM 1.2 to 2004 (or vice-versa) you would just need to change the CMI fields in your gets/sets, such as “cmi.learner_name” instead of “cmi.core.student_name”.

Since this SCORM for Developers series is focusing on SCORM 1.2, the ability to jump to SCORM 2004 will not have much impact here, but it’s worth mentioning in case you ever decide to give SCORM 2004 a whirl.

Packaging SCORM 1.2 Courses

A SCORM package normally consists of:

• A SCORM manifest (the imsmanifest.xml file) at the root of the package
• Supporting XML schema files
• Your course content

By spec, a SCORM course needs to be packaged in a Package Interchange Format (PIF) file, which is really just a plain old ZIP archive but with a PIF file extension instead of ZIP. In reality, most learning management systems accept ZIP files, so don’t worry about using the PIF extension.

Manifest

First, a little background on SCORM manifests. A SCORM manifest is just an XML file containing a specific set of nodes. These nodes provide details about your course, including title, version number, and location of course files (hence the name ‘manifest’, like a ship’s manifest). When the course package is imported into the LMS, the LMS analyzes the manifest, grabbing the course’s metadata and determining which HTML file should be used as the start page for the course.

As I explained earlier, the authors of SCORM had a grand vision of what SCORM could be, but a number of concepts in that vision never really panned out. As with the CMI data model, the SCORM manifest system was designed to support many intriguing options, including nested SCOs (a SCORM course within a SCORM course), standardizing how courses navigate between course pages, and roll-up rules that impact how a course is considered completed. And, like the CMI data model, most LMSs don’t uniformly support the full feature set.

SCORM documentation includes an entire book devoted to the manifest (“SCORM Content Aggregation Model”), which illustrates just how convoluted a manifest can become.

SCORM 1.2 listed many features as optional and left it up to the vendor to decide whether or not to implement the feature. As you can imagine, many vendors opted not to implement features, which caused headaches for developers who wanted to use the features.

With the release of SCORM 2004, the ADL set out to correct this issue by requiring all features to be implemented by LMS vendors. Coincidentally, SCORM 2004 also introduced many new sequencing and navigation options, making a SCORM 2004 implementation much more complex and expensive to implement than SCORM 1.2. As a result, some vendors complied with the new ADL requirements, but many did not, due to the complexity and cost of implementation.

This caused a chicken-or-egg scenario: E-learning authoring tools did not utilize any manifest features beyond the bare minimum because most LMSs did not support them. LMS vendors were quick to point out they didn’t need to support ‘advanced’ features because most e-learning authoring tools weren’t utilizing them.

I waited for years to see if LMS vendors would begin supporting the full feature set, as required by SCORM 2004’s stricter conformance rules. In the meantime, I followed the same path as the commercial vendors — for the sake of being ‘bulletproof’, I kept it simple, and it served me well. Two decades later, it’s safe to say most LMS vendors will never implement the full feature set, and I wholeheartedly recommend keeping your manifest as barebones as possible.

Also note: Using the LMS’s built-in course navigation (next, previous, table of contents, etc.) means your course UI (and therefore your learners’ experience) will be inconsistent from LMS to LMS. Using your own navigation system ensures your course will look and behave as expected, regardless of which LMS it has been loaded in.

Manifest Template

To help streamline my development workflow, I created a SCORM packaging template that covers the bare minimum required by SCORM. This template includes the manifest and the supporting XML schema files. To use this template for a new course, just copy the manifest and the SCORM-schemas folder to the root of your new course project, then edit a few details in the imsmanifest.xml file: course title, course version, course ID, and organization name.

You don’t need to understand everything going on here; all you need to do is change the values I’ve highlighted below to match your course.

<?xml version="1.0" standalone="no" ?>
<manifest identifier="CourseIDHere" version="1"
         xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
         xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.imsproject.org/xsd/imscp_rootv1p1p2 SCORM-schemas/imscp_rootv1p1p2.xsd
                             http://www.imsglobal.org/xsd/imsmd_rootv1p2p1 SCORM-schemas/imsmd_rootv1p2p1.xsd
                             http://www.adlnet.org/xsd/adlcp_rootv1p2 SCORM-schemas/adlcp_rootv1p2.xsd">
  <metadata>
    <schema>ADL SCORM</schema>
    <schemaversion>1.2</schemaversion>
  </metadata>
  <organizations default="course-code-here">
    <organization identifier="course-code-here">
      <title>Course Title here</title>
      <item identifier="item_1" identifierref="resource_1">
        <title>Course Title here</title>
      </item>
    </organization>
  </organizations>
  <resources>
    <resource identifier="resource_1" type="webcontent" adlcp:scormtype="sco" href="content/index.html">
      <file href="content/index.html" />
    </resource>
  </resources>
</manifest>

• Manifest identifier: This is your course’s ID. It needs to begin with a letter, and cannot contain spaces or special characters (hyphens and underscores are allowed).
• Manifest version: This is the version number for your course. In my experience, it doesn’t really matter what number you provide here, it’s largely for your own benefit.
• Organizations default: Many LMSs will use whatever you put here as the course code displayed in the LMS. Like the manifest identifier, it needs to begin with a letter, and cannot contain spaces or special characters (hyphens and underscores are allowed).
• Organizations identifier: I usually just mirror the value I provide under organizations default.
• Organization title: The title of your course.
• Item title: The title of your course (again).

And that’s it! Really simple, nothing to be afraid of.

You may have noticed there are two references to index.html. These are pointers to your course’s launch file — the file the LMS will open when the learner launches your course. If your course’s root HTML file ever has a filename other than index.html, you’d need to change these values to match. My courses are always set to use index.html, so I never need to edit these values.

You may also have noticed a few fields are redundant, such as two <title> elements. Why the redundancy? Without getting into the weeds, the SCORM manifest is designed to handle a variety of complex course configurations, including courses comprised of multiple SCORM packages (commonly known as multi-SCO courses). Since we are not using any of these advanced features, we end up with a streamlined manifest that has a couple of redundant fields.

A word about the resources node

By spec, every course asset contained in the ZIP file is supposed to be listed within the <resources> node as either a “sco” (the course’s primary launch file) or “asset” (any supporting file, including images, scripts, HTML, etc.). For example:

<resources>
    <resource identifier="resource_1" type="webcontent" adlcp:scormtype="sco" href="index.html">
        <file href="index.html" />
    </resource>
    <resource identifier="resource_2" type="webcontent" adlcp:scormtype="asset" href="page2.html">
        <file href="page2.html" />
    </resource>
    <resource identifier="resource_3" type="webcontent" adlcp:scormtype="asset" href="myscripts.js">
        <file href="myscripts.js" />
    </resource>
    <resource identifier="resource_4" type="webcontent" adlcp:scormtype="asset" href="mystyles.css">
        <file href="mystyles.css" />
    </resource>
    <resource identifier="resource_5" type="webcontent" adlcp:scormtype="asset" href="mypicture.jpg">
        <file href="mypicture.jpg" />
    </resource>
</resources>

As you can imagine, this is a major pain to deal with. Thankfully, most LMSs do not analyze the manifest’s nodes for anything apart from the adlcp:scormtype=”sco” file, which is used to launch the course. It’s usually safe to ignore the resource nodes.

However, some LMSs do use the <resource> nodes as a true manifest of goods (a list of everything the LMS will be needing to support the course) and will delete any files in your ZIP that are not listed in the manifest. This is rare but possible.

If you encounter this issue, there are a few open-source SCORM packaging tools floating around that you might find useful. You can also write a script that analyzes your course folder and writes up a list of files for you. I’ve posted an AppleScript demonstrating this technique on GitHub.

Zipping it up

As explained earlier, a SCORM package is a glorified ZIP archive. Once your content and manifest are settled, you’ll need to zip up the files.

It’s very important to leave the imsmanifest.xml file at the root of the ZIP file. If you don’t, the LMS will throw an error when you import your package. If you follow my technique for organizing files, your end result will look like this:

On a Mac, create the ZIP by selecting the files and right-clicking. Select “Compress”.

After zipping the folder, unzip it and ensure the resulting folder looks like the first image above.

Don’t try to compress the parent folder, this will lead to incorrectly nested files. The LMS will not be able to find the manifest and will give you an error.

One of the biggest obstacles for venturing into hand-built courseware is probably the lack of a built-in preview feature. This also impacts testing. When you use a commercial e-learning development tool, it typically includes a preview feature, enabling you to launch and interact with your course without loading it into an LMS. You can test things out and make smalls edits quickly. If you see an issue in your course, you close the preview window, make your edit, then relaunch the preview window, sometimes in a matter of seconds. The ability to quickly jump between the source material and the preview mode is a very alluring feature.

How can we do that if we’re building courses by hand? Sure, you can launch the course in your local web browser, but the browser won’t be able to provide the SCORM API, which means you can’t test the SCORM functionality. When you’re ready to test your SCORM tracking code, you’ll need to publish it to an LMS, which means setting up your SCORM manifest, packaging the course as a ZIP, uploading the ZIP to an LMS, configuring the course settings in the LMS, then launching the course in the LMS. If you discover a typo, or just want to make a small tweak to your code, you’ll (usually) need to go through the same steps again. It becomes very tedious very quickly.

This is why I break my testing into three phases:

1. Local testing using a web browser
2. Local testing using a faux LMS
3. Remote testing on a real LMS

Local testing using a web browser

In this first stage, I’m not worried about testing the tracking code. I’m more concerned about the basics: Ensuring my course navigation works, and that the user experience is as good as it can be. This includes ensuring the controls are accessible, and that the pages are responsive (they are flexible and will resize to fit different viewports). The first draft of a course might not even have any SCORM code in it, and should work in a web browser just like any other web site: you can open it, navigate, interact with it, etc.

This first stage is the best time to confirm the content, look, feel, and general functionality of the course before getting caught up in the LMS side of things. Ensure your content is accurate, that you don’t have any typos, that you have all of your final artwork in place, etc.

It’s critical that you test your course in different web browsers at this early stage of development. There are few things worse than developing a course which functions beautifully in one browser only to find it horribly broken in others. (Though, thankfully, this is less of an issue with modern browsers than it used to be.)

I generally do most of my initial development and testing in a single browser (typically Mozilla Firefox, simply because it’s my default browser), and jump to other browsers whenever I add new layouts or functionality to the course, such as a new interaction. Always ensure the new items look and behave as expected in all major browsers.

Don’t get hung up on making the courses look identical and pixel-perfect in every browser; each browser brings its own unique style and quirks to webpages, especially when using form elements such as drop-down menus. The focus should be on the content and functionality. Ask yourself if the user is receiving the same experience across all browsers, even if a few items (scrollbars, form fields, etc.) look different.

This is also a good time to ensure the courseware is keyboard accessible. In my opinion, being able to navigate the entire course using a keyboard (no mouse or trackpad) is a requirement, and should not be an afterthought. Many screen readers and assistive technologies use keyboard mappings to help their users navigate the course. Of course, accessibility runs much deeper than keyboard access, but this is an excellent way to train yourself to remember accessibility while you develop your courseware.

Finally, if you have a subject-matter expert, instructional designer, or client who needs to review and sign off on the course, do it at this stage if possible. It will save you from hassles down the road, since you can quickly update content without jumping through LMS hoops.

Notes

• Tools like BrowserStack and LambdaTest are an easy way to test your course across browsers and platforms.
• See sites such as https://www.w3counter.com/trends for the latest trends in browser market share.
• I like to test courses across the following browsers and platforms:Google Chrome (macOS and Windows)Firefox (macOS and Windows)Microsoft Edge (Windows only)Safari (macOS only)
• I sometimes test in Opera, but it has significantly smaller marketshare, and uses the same Blink rendering engine as Chrome. I don’t consider Opera a hard requirement. (This may not be the case for some European course developers, as Opera is much more widely used in Europe than the United States.)
• Microsoft Edge also uses the same rendering engine as Chrome, so if the course works in Google Chrome, it typically also works in Opera and Edge.
• If you plan to support mobile devices, you should test Safari for iOS as well as Chrome for Android devices.

Local testing using a faux LMS

In the second phase of testing, I test locally using a home-built faux-LMS. The faux LMS is basically a simple one- or two-page website running on my local machine. It reads files from my local filesystem, enabling it to display a list of local courses, which launch in a popup window when clicked.

The system uses a stripped-down SCORM API and saves the SCORM data to the web browser’s LocalStorage. All SCORM calls are properly recorded, including bookmarks. I can exit a course then resume it, just as you would on a production LMS.

This sounds very complicated, but in reality the experience is almost the same as simply viewing the course in a web browser. The only differences are that the course can be launched in a constrained pop-up window (mimicking an LMS experience) and the course will have SCORM tracking support.

Using a faux LMS is a real time-saver compared to using a true LMS, as it allows me to test files locally without uploading the entire course to an LMS, doesn’t require creating a ZIP package, and doesn’t require any fiddling with course settings or versioning in the LMS user interface. If I were using a real LMS, a task such as fixing a simple typo would require creating a new ZIP, uploading the ZIP to the LMS, then dealing with the LMS’s versioning system. And many times, when you launch the edited course you will run into caching issues, where the old version of the file remains cached on the LMS for some reason. In the faux LMS environment, if I spot a typo on a course page, I can quickly edit that file locally without having to repackage and re-upload to the LMS.

Unfortunately, I’m not ready to share my faux-LMS systems yet (sorry for being a tease!), but if you’d like to try something similar, look into open-source systems like Jonathan Putney’s SCORM Again or Tim St Clair’s SCORM Debug.

Remote testing on a real LMS

For the third phase of testing, I upload the course to a staging LMS to confirm it works as expected. This staging system is typically a clone of a production LMS, specifically provided to developers for testing courses.

If you don’t have a staging LMS, you may want to consider installing an installing an open-source LMS locally. It takes some effort, but will give you decent results. Some LMSs to consider are Moodle, Chamilo, Forma, and Ilias. Alternatively, you can use a third-party service such as Rustici Software’s SCORM Cloud. To be honest, SCORM Cloud is one of the best ways to test a course, as it provides very useful SCORM logs and error messages, which can help pinpoint any SCORM-related issue you may be encountering. SCORM Cloud provides free accounts for testing smaller courses, but requires payment for larger courses. It also requires uploading your files to their servers, which may present security and/or confidentiality issues for some clients.

Regardless, testing on a staging system is crucial for verifying the functionality of the course in a production environment before releasing it to your learners. Always check the course in a true LMS environment before assigning the course to learners.

Since LMS platforms vary, they sometimes introduce cross-platform issues. Even though you may have tested your course across browsers and platforms locally, you should do it again when your course has been loaded in the LMS. It’s always better to catch these issues yourself than having your boss/customer or end users (learners) finding them for you.

In short, test, test, and test again.

Don’t be alarmed by the fast pace of this lesson — this is just a quick primer covering the basic concepts and architecture. Remember, this is a non-functioning example. We will walk through fully functional examples line-by-line later in the series.

Checking Lesson Status

The previous lesson included the CMI field cmi.core.lesson_status. This field is responsible for maintaining the status of the course. It’s a read/write field, which means you can retrieve its value, and you can also change its value.

cmi.core.lesson_status is not a free-form text field, and will only accept specific values (referred to as tokens in the SCORM documentation). The allowed values for cmi.core.lesson_status are:

• “not attempted” — the default status.
• “incomplete” — the course has been started but the learner has not finished it.
• “completed” — indicates course is completed but does not indicate whether the appropriate passing score was reached.
• “passed” — indicates course is both completed and passed.
• “failed” — the opposite of “passed”, the course is likely completed but the learner hasn’t met the criteria for passing (the criteria is defined by you, within your own course logic, not by SCORM).
• “browsed” — the course has been launched in “browse mode”.I don’t recommend using browse mode, as I find it often creates confusion regarding completion status and score. There are other techniques available for enabling a learner to relaunch a course after completion without altering the score, which will be covered later in this series.

The statuses you’ll use most often are “incomplete” coupled with either “completed” or “passed”, depending on your preference and needs. You might use “failed”, but who are we kidding, most courses are built to never let the learner fail! (But by all means, use it if it fits your scenario.)

It’s a best practice to check the course status immediately upon launching your course. This will enable you to properly handle several scenarios:

1. If this is the first time the learner has launched the course, the value will typically be “not attempted”. In most cases, you will want to immediately change the value to “incomplete”, which officially denotes (implies) the learner has accessed the course at least once.
2. If the course status is set to “incomplete”, in most cases this is where you would insert some code to check for a bookmark, so you can redirect the learner to where they left off when they exited the course.
3. If the course status is set to “completed” or “passed”, you can assume the learner is back to review content. In this scenario, you’d disable tracking in your course, freeing the learner to navigate and interact with the course without fear of altering the course status (and score, if applicable) achieved when they initially completed the course.

For the purposes of our little example, let’s keep it simple and check to see if the course has already been set to “completed” or “passed” before we try to change the value of cmi.core.lesson_status. We can do this by using LMSGetValue, which, as you may have guessed, retrieves the value of a CMI field from the LMS.

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<script>

var API = window.API;

//begin the SCORM session
API.LMSInitialize("");

//Get the lesson status from LMS
var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

//Only set the status to "completed" if it is not already considered completed
if(lesson_status !== "completed" && lesson_status !== "passed"){

   //Explicitly set course status to “completed”
   API.LMSSetValue("cmi.core.lesson_status", "completed");

   //Don’t forget to commit!
   API.LMSCommit("");

}

//end the SCORM session
API.LMSFinish(""); 

</script>
</body>
</html>

In this example, the conditional statement will only set the course to “completed” if it hasn’t already been set to “completed” or “passed”. If the course has been completed, don’t try to set the course to “completed” again, just leave it be.

Error Checking

Some will say it’s a good practice to include error-checking. I say it’s imperative. Case in point: What happens when LMSInitialize isn’t successful? (It’s rare, but it happens.)

If LMSInitialize is not successful, and you don’t account for it in your course logic, the learner will continue to interact with the course, thinking the course is functioning normally, but the LMS will not be saving any information about the course session. In our little example, the learner would only miss out on the completion status, but in the real world, a learner could navigate through dozens of course pages and not receive credit. You’d spend the next week answering angry support calls!

Thankfully, LMSInitialize returns a value indicating whether initialization was successful.

As seen in the code example below, we can perform a check to ensure LMSInitialize is successful before moving on to our other course functions. If LMSInitialize is not successful, we can alert the user.

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<script>

var API = window.API;

//begin the SCORM session
var isInitialized = (API.LMSInitialize("") === "true"); //create a boolean value

if(isInitialized){

   //Get the lesson status from LMS
   var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

   //Only set the status to "completed" if it is not already considered completed
   if(lesson_status !== "completed" && lesson_status !== "passed"){

      //Explicitly set course status to “completed”
      API.LMSSetValue("cmi.core.lesson_status", "completed");

      //Don’t forget to commit!
      API.LMSCommit("");

   }

   //end the SCORM session
   API.LMSFinish(""); 

} else {

   alert("Uh-oh, LMSInitialize failed!");

}

</script>
</body>
</html>

The course now validates the initialization, and alerts the learner if the initialization failed.

As you can see, error-checking doesn’t have to be difficult, but it’s very important, both for reliability of your course and for user satisfaction. Many of the older SCORM tutorials on the interwebs don’t utilize error-checking, which I feel is a big mistake. We will continue to implement error-checking strategies throughout the examples in this series.

Notes

• In yet another quirk of the SCORM API, LMSInitialize returns a ‘string boolean.’ Instead of an authentic boolean (true or false), we get the stringified versions (“true” and “false”). We need to account for these in our script.
• Some LMSs don’t return “true” or “false” as specified by the SCORM spec. This is one instance where SCORM wrappers come in handy. SCORM wrappers will be covered a bit later.

Personalization

Another nice touch we can add is personalization. The CMI field cmi.core.student_name provides the learner’s name, which we can dynamically insert into the course. Building on our example code, we can add a small bit of HTML markup, and a touch of JavaScript to populate it with the learner’s name.

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<p>Hello, <span id="learner_name"></span>.</p>

<script>

var API = window.API;

//Grab a reference to the learner_name span for future use
var name_span = document.querySelector("#learner_name");

//begin the SCORM session
var isInitialized = (API.LMSInitialize("") === "true"); //create a boolean value

if(isInitialized){

   //Get the learner's name from the LMS
   var learner_name = API.LMSGetValue("cmi.core.student_name");

   //Populate the learner_name span element with the learner's name
   name_span.innerHTML = learner_name;

   //Get the lesson status from LMS
   var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

   //Only set the status to "completed" if it is not already considered completed
   if(lesson_status !== "completed" && lesson_status !== "passed"){

      //Explicitly set course status to “completed”
      API.LMSSetValue("cmi.core.lesson_status", "completed");

      //Don’t forget to commit!
      API.LMSCommit("");

   }

   //end the SCORM session
   API.LMSFinish(""); 

} else {

   alert("Uh-oh, LMSInitialize failed!");

}

</script>
</body>
</html>

It may seem like a minor improvement, but in my opinion, including your learner’s name on the screen helps improve confidence in the course. It also provides the opportunity to personalize any interactive sections you may build within the course. For example, you can create prompts for interactions such as “OK, Jane, are you ready to give it a try?”

Notes

• When sending cmi.core.student_name, LMSs usually include both first name (given name) and last name (surname). There is no official standard for whether the name is returned in a specific sequence, such as “Jane Doe” or “Doe, Jane”, so be careful how you choose to use the cmi.core.student_name field.

Require User Interaction

As currently constructed, the course doesn’t require any interaction from the learner to earn their course completion. Let’s require the learner to do something before granting the completion. For simplicity’s sake, we’ll just require a button click. To do this, we add a button to the HTML, then add a bit of JavaScript to handle what happens when the button is clicked.

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<p>Hello, <span id="learner_name"></span>.</p>
<button id="btn_complete">Click me to complete this course</button>

<script>

var API = window.API;

//Grab a reference to the learner_name span for future use
var name_span = document.querySelector("#learner_name");

//Grab a reference to the button for future use
var btn = document.querySelector("#btn_complete");

//Set up a click handler for the button
btn.addEventListener("click", function(e){
   //Ensure the browser only does what we tell it to when the button is clicked
   e.preventDefault();
});

//begin the SCORM session
var isInitialized = (API.LMSInitialize("") === "true"); //create a boolean value

if(isInitialized){

   //Get the learner's name from the LMS
   var learner_name = API.LMSGetValue("cmi.core.student_name");

   //Populate the learner_name span element with the learner's name
   name_span.innerHTML = learner_name;

   //Get the lesson status from LMS
   var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

   //Only set the status to "completed" if it is not already considered completed
   if(lesson_status !== "completed" && lesson_status !== "passed"){

      //Explicitly set course status to “completed”
      API.LMSSetValue("cmi.core.lesson_status", "completed");

      //Don’t forget to commit!
      API.LMSCommit("");

   }

   //end the SCORM session
   API.LMSFinish(""); 

} else {

   alert("Uh-oh, LMSInitialize failed!");

}

</script>
</body>
</html>

In this updated code, we’ve added the button to click, and a click handler, but the click handler doesn’t actually do anything yet.

This button’s purpose is to set the course to “completed” when clicked, so let’s cut and paste the relevant parts of the lesson_status check into the click handler:

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<button id="btn_complete">Click me to complete this course</button>

<script>

var API = window.API;
var btn = document.querySelector("#btn_complete");

btn.addEventListener("click", function(e){

   //Ensure the browser only does what we tell it to when the button is clicked
   e.preventDefault(); 

   if(isInitialized){

      //Get the lesson status from LMS
      var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

      //Only set the status to "completed" if it is not already considered completed
      if(lesson_status !== "completed" && lesson_status !== "passed"){

         //Explicitly set course status to “completed”
         API.LMSSetValue("cmi.core.lesson_status", "completed");

         //Don’t forget to commit!
         API.LMSCommit("");

      }

      //end the SCORM session
      API.LMSFinish(""); 

   } else {

      alert("Can't set the course to complete: it hasn't been initialized");

   }

});

//begin the SCORM session
var isInitialized = (API.LMSInitialize("") === "true"); //create a boolean value

if(isInitialized){

   //do nothing

} else {

   alert("Uh-oh, LMSInitialize failed!");

}

</script>
</body>
</html>

Note I’ve wrapped the completion code in an if() statement, ensuring it will only be invoked if the course was properly initialized.

As currently constructed, when the course is launched, it will initialize the SCORM connection, but won’t do anything else. When the learner clicks the button, the course will be set to “completed” and the SCORM connection will be terminated.

So far, so good. But let’s improve the user experience by providing textual feedback to the learner when the button is clicked.

First we need to provide a place to put the text. In the <body>, we’ll add a heading, and some instruction for the learner. Then we’ll dynamically change the text when the button is clicked.

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<h1>Course Title</h1>

<p>Hello, <span id="learner_name"></span>.</p>

<div id="message">
Please click the button to indicate you have completed this course.
</div>

<button id="btn_complete">Click me to complete this course</button>

<script>

var API = window.API;

//Grab a reference to the learner_name span for future use
var name_span = document.querySelector("#learner_name");

//Grab a reference to the button for future use
var btn = document.querySelector("#btn_complete");

//Grab a reference to the 'message' div for future use
var message_div = document.querySelector("#message");

//Set up a click handler for the button
btn.addEventListener("click", function(e){

   //Ensure the browser only does what we tell it to when the button is clicked
   e.preventDefault();

   if(isInitialized){

      //Get the lesson status from LMS
      var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

      //Only set the status to "completed" if it is not already considered completed
      if(lesson_status !== "completed" && lesson_status !== "passed"){

         //Explicitly set course status to “completed”
         API.LMSSetValue("cmi.core.lesson_status", "completed");

         message_div.innerHTML = "Course set to completed. Congratulations!";

         //Don’t forget to commit!
         API.LMSCommit("");

      } else {

         message_div.innerHTML = "Course has already been completed.";

      }

      //end the SCORM session
      API.LMSFinish(""); 

   } else {

      alert("Can't set the course to complete: it hasn't been initialized");

   }

});

//begin the SCORM session
var isInitialized = (API.LMSInitialize("") === "true"); //create a boolean value

if(isInitialized){

   //Get the learner's name from the LMS
   var learner_name = API.LMSGetValue("cmi.core.student_name");

   //Populate the learner_name span element with the learner's name
   name_span.innerHTML = learner_name;

} else {

   alert("Uh-oh, LMSInitialize failed!");

}

</script>
</body>
</html>

The value of <div id=”message”> changes based on the outcome of the button click. It sounds so simple, but is a very powerful way to improve the user experience.

With this change, the learner gets feedback as soon as the button is clicked. If the course is properly initialized, and the course has not already been completed, the learner is informed the course is now complete. If the initialization failed, the learner is informed of the failure. If the course has already been completed, the learner is informed of the prior completion.

Let’s take a moment to further improve the user experience. Now that we’ve established an on-screen location for providing feedback to the learner, we can replace all of the alert() calls with on-screen text. This is much less annoying than a parade of pop-up alerts. We can also hide the button after it has been clicked, since it’s no longer needed and we don’t want the learner to continue to click it.

<!DOCTYPE html>
<html>
<head>
   <meta charset="UTF-8">
   <title>SCORM Course</title>
</head>
<body>

<h1>Course Title</h1>

<p>Hello, <span id="learner_name"></span>.</p>

<div id="message">
Please click the button to indicate you have completed this course.
</div>

<button id="btn_complete">Click me to complete this course</button>

<script>

var API = window.API;

//Grab a reference to the learner_name span for future use
var name_span = document.querySelector("#learner_name");

//Grab a reference to the button for future use
var btn = document.querySelector("#btn_complete");

//Grab a reference to the 'message' div for future use
var message_div = document.querySelector("#message");

//Set up a click handler for the button
btn.addEventListener("click", function(e){

   //Ensure the browser only does what we tell it to when the button is clicked
   e.preventDefault();

   if(isInitialized){

      //Get the lesson status from LMS
      var lesson_status = API.LMSGetValue("cmi.core.lesson_status");

      //Only set the status to "completed" if it is not already considered completed
      if(lesson_status !== "completed" && lesson_status !== "passed"){

         //Explicitly set course status to “completed”
         API.LMSSetValue("cmi.core.lesson_status", "completed");

         message_div.innerHTML = "Course set to completed. Congratulations!";

         //Don’t forget to commit!
         API.LMSCommit("");

      } else {

         message_div.innerHTML = "Course has already been completed.";

      }

      //end the SCORM session
      API.LMSFinish(""); 

   } else {

      message_div.innerHTML = "Can't set the course to complete: it hasn't been initialized";

   }

   //hide the button so it can't be clicked anymore
   btn.style = "display:none;";

});

//begin the SCORM session
var isInitialized = (API.LMSInitialize("") === "true"); //create a boolean value

if(isInitialized){

   //Get the learner's name from the LMS
   var learner_name = API.LMSGetValue("cmi.core.student_name");

   //Populate the learner_name span element with the learner's name
   name_span.innerHTML = learner_name;

} else {

   message_div.innerHTML = "Uh-oh, LMSInitialize failed!";

}

</script>
</body>
</html>

Three lines of JavaScript can make a big difference for the user experience.

Lesson Wrap-Up

And there you have it: a simple, usable SCORM course.

Again, we’re using a fake API connection (window.API) for simplicity’s sake, so this example will not function in a real LMS yet.

Granted, this example is terribly contrived and would not be very useful (or fun) in a real-world environment, but everything except the API connection is fully-functioning and valid.

We breezed through this exercise rather quickly, but I hope you get the gist of the lesson: SCORM code is just a tiny bit of JavaScript and nothing to be afraid of. In fact, I’ll argue that the SCORM code within most e-learning courses is usually the smallest component of the codebase — the course’s presentation and navigation scripts are usually the most complex pieces of the puzzle.

Check the next few installments of this series for examples that will run in real-world LMS. These examples will utilize open-source JavaScript libraries to handle the presentation and navigation features, and we’ll bolt on the SCORM code to make them LMS-ready.

Later in the series, when we’ve established more of a comfort level with SCORM code and course-building concepts (bookmarking, scoring, etc.), we will build a simple-yet-complete HTML course from scratch.

The HTML

First, create a vanilla HTML page.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>SCORM Course</title>
  </head>
  <body></body>
</html>

This is a barebones HTML5 document. Nothing special.

Next, we’ll add a wee bit of JavaScript. SCORM courses use JavaScript to push and pull data from the LMS, such as the learner’s name, course status, and a bookmark for learner’s current location within the course. This is done by connecting to the SCORM application programming interface (API), which the LMS makes available in the browser’s window object. (More on this later.)

Let’s add a JavaScript <script> element to our HTML file. In the old days, this would have been placed in the <head>, but modern convention is to place it inside <body>, right before the </body> tag.

(For you old-timers, I’m using the HTML5 convention of <script> without type=“text/javascript” or lang=“javascript” — HTML5 assumes every <script> block is JavaScript, so you no longer need to specify type=“text/javascript” or lang=“javascript”.)

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>SCORM Course</title>
  </head>
  <body>
    <script></script>
  </body>
</html>

The JavaScript

As I mentioned above, the LMS makes the SCORM API available in the window JavaScript object. Since this is a contrived SCORM 1.2 example, we can pretend the SCORM 1.2 API is already available at window.API. In the real world, the API is typically in a parent frame or different browser window; you would never actually find the API in window.API. We will discuss the API in a later lesson, for now let’s just pretend it’s at window.API.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>SCORM Course</title>
  </head>
  <body>
    <script>
      var API = window.API;
    </script>
  </body>
</html>

Here’s where the fun starts. We will need to invoke the SCORM API to perform specific tasks. By spec, a SCORM course is only required to start (LMSInitialize) and stop (LMSFinish) a SCORM session. No other actions are required.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>SCORM Course</title>
  </head>
  <body>
    <script>
      var API = window.API;
      //begin the SCORM session
      API.LMSInitialize("");
      //end the SCORM session
      API.LMSFinish("");
    </script>
  </body>
</html>

Believe it or not, this is it — a course that meets the minimum requirements for SCORM conformance!

Explicitly Setting the Completion Status

Despite there being no attempt to set a course status or score, this minimalist code will normally result in a completion immediately upon launching the course. Why? By spec [SCORM Version 1.2 3-25], if the course does not manually specify a completion status value (via cmi.core.lesson_status) before the course session is terminated, the LMS is required to set the status to “completed”.

This brings us to a key premise of this tutorial series: LMSs don’t always adhere to the SCORM spec. Working off of assumptions can be dangerous. In this example, we should play it safe and explicitly indicate the completion status, not trusting the LMS to set it for us.

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>SCORM Course</title>
  </head>
  <body>
    <script>
      var API = window.API;
      //begin the SCORM session
      API.LMSInitialize("");
      //Explicitly set course status to “completed”
      API.LMSSetValue("cmi.core.lesson_status", "completed");
      //Don’t forget to commit!
      API.LMSCommit("");
      //end the SCORM session
      API.LMSFinish("");
    </script>
  </body>
</html>

LMSSetValue enables the course to set the value of a specific data field in the LMS. In this example, we’re setting the value of the data field cmi.core.lessonstatus to “completed”. LMSCommit specifically instructs the LMS to write the data into the LMS’s database. Think of it as clicking the _save button.

And this, in all its glory, is a bare-minimum HTML-based SCORM course.

Just remember, this is a contrived example and doesn’t take any real-world concerns into account, such as what happens if window.API can’t be found, or if LMSInitialize("") fails. This example is not ready for testing in an LMS yet. We’ll get there, I promise!

In the next lesson, we’ll modify this example to include lesson status, error-handling, and some personalization.

Notes

1. A course can only invoke LMSInitialize and LMSFinish once each; if the session is closed, it cannot be re-initialized. You would need to close the course and relaunch it from the LMS. Also note that due to the SCORM spec, an empty string must be passed for both LMSInitialize("") and LMSFinish(""). Just one of those crazy SCORM quirks.
2. A word about LMSCommit: Whenever you set a value using LMSSetValue, you are sending the value to a JavaScript object in the web browser, not to the LMS itself. The data in the JavaScript object is not pushed to the server (the LMS’s database) until you invoke API.LMSCommit(""). Failure to invoke LMSCommit("") is a common blunder, causing an otherwise perfectly-crafted course to fail spectacularly. The flip side, however, is that if you invoke LMSCommit too often, it may “clog the pipes” and lead to performance issues with your course and/or LMS. This has been the case with some older off-the-shelf e-learning development tools. The best practice is to avoid invoking LMSCommit after every SetValue, and to strategically invoke it after a series of related SetValue calls. We will dive deeper in a future lesson.

Commercial course creation tools like Adobe Captivate, Articulate Rise, and iSpring are hyper-focused on broad compatibility with as many LMSs as possible. Acknowledging they couldn’t trust LMSs to provide full SCORM support, the tools were designed to utilize only the most commonly supported SCORM elements, which I refer to as the Safe Parts (hat tip to Doug Crockford). If you limit your course’s use of SCORM to this subset of features, your course will work pretty much anywhere.

Note that my Safe Parts recommendations are based on SCORM 1.2, which has the greatest market share. If you prefer to use SCORM 2004, I consider the SCORM 2004 equivalents safe as well, though there can be some hiccups here and there depending on which version of SCORM 2004 has been implemented.

API Safe Parts

The API, owing to its simplicity, works pretty much as outlined in the SCORM documentation, and doesn’t usually need any special handling.

CMI Data Model Safe Parts

The CMI data model has some truly useful fields. Unfortunately, most course development tools don’t support SCORM’s full CMI data model because of the old chicken or egg conundrum: LMSs don’t consistently support the full CMI data model, so course vendors don’t use it. Since course vendors don’t use it, LMS vendors don’t spend the time and money to implement it.

The following SCORM 1.2 CMI data fields are the closest thing you’ll get to bulletproof in the LMS ecosystem.

• cmi.core.student_id (read-only)A unique identifier for the learner who launched the course, provided by the LMS.String, 255 characters max.
• cmi.core.student_name (read-only)Name of learner, as provided by the LMS.String, 255 characters max.
• cmi.core.lesson_location (read-write)A string that can be used to ‘bookmark’ the learner’s location within a course.String, 255 characters max.
• cmi.core.lesson_status (read-write)The status of the learner’s progress for the course.Only accepts the following strings: “passed”, “completed”, “failed”, “incomplete”, “browsed”, “not attempted”.
• cmi.core.score.min (read-write)cmi.core.score.min and cmi.core.score.max establish the range of scoring possible within the course, such as 0-100.Use cmi.core.score.min to specify the lowest possible score.Value must be a number, passed as a string.“A number that may have a decimal point. Examples are ‘2’,’2.2’.” (SCORM 1.2 Run-Time Environment, 3-57)
• cmi.core.score.max (read-write)cmi.core.score.min and cmi.core.score.max establish the range of scoring possible within the course, such as 0-100.Use cmi.core.score.max to specify the highest possible score.Value must be a number, passed as a string.“A number that may have a decimal point. Examples are ‘2’,’2.2’.” (SCORM 1.2 Run-Time Environment, 3-57)
• cmi.core.score.raw (read-write)Learner’s current score.Must fall between the values established by cmi.core.score.min and cmi.core.score.raw.Value must be a number, passed as a string.“A number that may have a decimal point. Examples are ‘2’,’2.2’.” (SCORM 1.2 Run-Time Environment, 3-57)
• cmi.core.exit (write-only)Indicates learner’s reason for leaving the course.Only accepts the following strings: “time-out”, “suspend”, “logout”, “” (empty string).
• cmi.suspend_data (read-write)Essentially a blank database field for storing anything you might need.Frequently used to store data about the course’s state, such as which pages have been visited and which have not been accessed yet.String, 4096 characters max.LMSs are often lax on the cmi.suspend_data storage limit; some will allow much larger amounts of data. Do not assume if one LMS permits you to store over 4096 characters that other LMSs will follow suit.

Additionally, there are some fields that are likely safe, but should be tested in your LMS if you decide to use them:

• cmi.core.entry (read-only)Indicates whether the learner is accessing the course for the first time (“ab-initio”) or is returning to an existing session (“resume”).Only returns the following strings: “ab-initio”, “resume”, “”.
• cmi.core.session_time (write-only)The amount of time the student has spent in the course for the given session, from launch to closing the course. cmi.core.total_time provides a sum of all the individual sessions.String, formatted as HHHH:MM:SS.SS.“Hours have a minimum of 2 digits and a maximum of 4 digits. Minutes shall consist of exactly 2 digits. Seconds shall contain 2 digits, with an optional decimal point and 1 or 2 additional digits. (i.e. 34.45).” (SCORM 1.2 Run-Time Environment, 3-58)
• cmi.core.total_time (read-only)“Accumulated time of all the student’s sessions in the SCO”. (SCORM 1.2 Run-Time Environment, 3-29)String, formatted as HHHH:MM:SS.SS.“Hours have a minimum of 2 digits and a maximum of 4 digits. Minutes shall consist of exactly 2 digits. Seconds shall contain 2 digits, with an optional decimal point and 1 or 2 additional digits. (i.e. 34.45).” (SCORM 1.2 Run-Time Environment, 3-58)

I hesitate to include cmi.core.session_time and cmi.core.total_time; I’ve seen LMSs that utilize their own codebase to track the learner’s time in the course, ignoring values submitted by the course. Having said that, I do not see harm in using these fields, as long as you don’t rely on them for critical course functionality.

Manifest Safe Parts

In courses produced by commercial tools like Captivate, the manifest is extremely simple. It’s usually just a handful of XML nodes. This is because the course is a monolithic course — a ‘single SCO’ course, meaning it’s completely self-contained, and manages its own internal navigation.

If you were to try to implement SCORM as originally envisioned, the navigation would need to be handled by the LMS, which would require listing every single HTML page in your course, plus navigation instructions (the sequencing and navigation piece). SCORM’s Content Aggregation Model (CAM) took it even further, enabling SCOs (courses) to contain other SCOs and promoting “reusability of learning content across LMSs and repositories“.

A grand vision, never embraced by enterprise LMS vendors.

For our purposes, the safest approach is to emulate commercial course development tools and implement a single-SCO methodology. We will only use the bare minimum, as outlined in this template I posted on GitHub.

<?xml version="1.0" standalone="no" ?>
<manifest identifier="CourseIDHere" version="1"
         xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
         xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.imsproject.org/xsd/imscp_rootv1p1p2 SCORM-schemas/imscp_rootv1p1p2.xsd
                             http://www.imsglobal.org/xsd/imsmd_rootv1p2p1 SCORM-schemas/imsmd_rootv1p2p1.xsd
                             http://www.adlnet.org/xsd/adlcp_rootv1p2 SCORM-schemas/adlcp_rootv1p2.xsd">
  <metadata>
    <schema>ADL SCORM</schema>
    <schemaversion>1.2</schemaversion>
  </metadata>
  <organizations default="course-code-here">
    <organization identifier="course-code-here">
      <title>Course Title here</title>
      <item identifier="item_1" identifierref="resource_1">
        <title>Course Title here</title>
      </item>
    </organization>
  </organizations>
  <resources>
    <resource identifier="resource_1" type="webcontent" adlcp:scormtype="sco" href="index.html">
      <file href="index.html" />
    </resource>
  </resources>
</manifest>

A working example will be provided later in this series.

Here’s a quick overview of each component. I will provide real-world examples later in this series.

The SCORM API

The SCORM API is a JavaScript object made available through the browser’s window object. The API allows the course to issue commands to the LMS, such as getting/setting data and exiting a course. The LMS is responsible for providing the API and exposing it via window to the course.

There are eight methods (functions) provided by the SCORM 1.2 API:

1. LMSInitialize("")Starts the SCORM session.Returns a boolean in string format, indicating success of call.Quirk: Always requires a single parameter, set to an empty string.
2. LMSFinish("")Ends the SCORM session.Returns a boolean in string format, indicating success of call.Quirk: Always requires a single parameter, set to an empty string.
3. LMSGetValue(cmi_field)Retrieves and returns the value of the specified CMI field.Value provided in string format.
4. LMSSetValue(cmi_field, value)Sets the value of the specified CMI field.All values must be submitted as a string, including numbers and objects (e.g. “23” instead of 23).Returns a boolean in string format, indicating success of call.
5. LMSCommit("")Instructs the LMS to persist (save) the course data to the database.Returns a boolean in string format, indicating success of call.Quirk: Always requires a single parameter, set to an empty string.
6. LMSGetLastError()Retrieves and returns the error code generated by the previous SCORM API call.Error code is a number provided in string format.
7. LMSGetErrorString(error_code)Retrieves and returns a brief message describing the error specified by error_code.Message provided in string format.
8. LMSGetDiagnostic(error_code)Retrieves and returns a more detailed message about the error specified by error_code.Message provided in string format.

SCORM 2004 renamed the API methods, but the API functionality is identical:

• Initialize()
• Terminate()
• GetValue()
• SetValue()
• Commit()
• GetLastError()
• GetErrorString()
• GetDiagnostic()

The CMI Data Model

SCORM is a reference model (hence the RM in SCORM), which means it repurposes existing standards. The CMI (computer managed instruction) data model was part of the AICC specification, which preceded SCORM_._

The CMI data model can be thought of as a list of fields available in a database, including items like learner’s name and the most recent course bookmark.

The meat of the SCORM system lies in the CMI data model, which provides course developers with access to specific bits of data, including the student’s name via cmi.core.student_name, the score via cmi.core.score.raw, the course bookmark via cmi.core.lesson_location field, etc.

SCORM’s CMI fields, especially with SCORM 2004, are actually pretty diverse and support many useful tasks: track course objectives, track user interactions (including answers provided by the learner, and how much time they spent in the interaction), gather comments from the learner as they progress through the course, and enable the learner to specify preferences about language, audio playback, and more.

You can explore the full list of available CMI fields on Rustici Software’s handy SCORM Run-Time Reference Guide.

The Course Manifest

A SCORM course requires a manifest XML file, which contains key metadata such as course name, course ID, and version number. It also contains nodes informing the LMS where to find your course files.

The manifest is always named imsmanifest.xml and is always located at the root of the SCORM package.

The file is named imsmanifest because it utilizes the IMS Global Learning Consortium’s content packaging standards. (Note the IMS Global Learning Consortium has rebranded to 1EdTech Consortium.)

I’ve previously written about manifests, and examples can be found on GitHub. I will provide a functional example later in this series.

In the mid-1990s, the Internet — still spelled with a capital “I” — was booming, and new learning management systems were popping up left and right. The LMS ecosystem was a bit of the Wild West, as each LMS tended to use its own proprietary code for tracking score, managing bookmarks, and sending course data to the LMS. Vendor lock-in made courses difficult to produce, maintain, and reuse. If you wanted to port the course from one LMS to another, you’d need to rewrite the underlying tracking code (and course packaging) to be compatible with each LMS.

The US government, including the Department of Defense, recognized the inefficiencies and wanted to bring order to the chaos. In the late 1990s, they created a federal program called the Advanced Distributed Learning (ADL) Initiative to create “standards, tools, and learning content for the future learning environment.”

Rather than reinvent the wheel, the ADL team opted to borrow fragments of existing standards to form their new reference model.

Note: Although SCORM is often referred to as a “standard”, it is in fact not a standard — it’s a curated collection of standards that had been previously created by other organizations. For example, the CMI data model is from the Aviation Industry Computer-Based Training Committee (AICC) group, and is an adaptation of an IEEE standard. SCORM’s packaging system is from the IMS Global Learning Consortium, hence the SCORM package requiring a file named imsmanifest.xml.

SCORM 1.0 was released in January, 2000, providing guidance for standardizing the structure of e-learning course packages and the communication between the course and LMS. The result would be portable SCOs (shareable content objects, a.k.a. courses) that work in any SCORM-compliant LMS.

A simplistic, contrived example: Prior to SCORM, if the US Army purchased an e-learning course explaining how to use a fire extinguisher, the course could not be shared with the Navy, Air Force, or Marines because the course had been customized for the Army’s learning management system. In this contrived scenario, each military branch used its own proprietary learning management system, none of which were compatible with the Army’s course. They would have to either buy a different course to fill the same need, or pay a developer to modify the Army’s existing course to work in their system(s).

By using SCORM to standardize communication and packaging techniques for e-learning courses, the courses become portable and reusable, reducing redundancies and likely saving a lot of time and money.

Since SCORM was a US government initiative, US federal agencies quickly added SCORM support as a requirement in their contracts, helping SCORM gain widespread adoption within a few years. Millions of government dollars were up for grabs, and the e-learning industry jumped at the opportunity. LMS vendors added SCORM support to their platforms, and course developers began producing SCORM packages.

SCORM 1.2 (released 2001) was the first widely adopted version of SCORM, and still holds the most market share. SCORM 1.3, more commonly known as SCORM 2004, was released a few years later, and was much more ambitious. It introduced some much-needed improvements to SCORM 1.2, but was also much more complex. SCORM 2004 included a new sequencing and navigation model that was incredibly difficult to implement, leading most LMS vendors to ignore it or (even worse) only support a subset of its features. SCORM 2004 has four editions, the most common of which are SCORM 2004 2nd Edition and SCORM 2004 3rd Edition. The first and fourth editions have very little market share.

In early 2011 the ADL “put a lid” on SCORM, making SCORM 2004 4th Edition the last official release. SCORM is no longer maintained or updated.

And that’s the 60-second history of SCORM. Of course, there are many details I’m leaving out for the sake of brevity, including SCORM’s unintentional(?) enforcement of specific instructional models and pedagogies, but those are topics for another day.

Some may ask: Why hand-coded, and why SCORM?

Let’s address the SCORM question first.

There are a dozen reasons why e-learning developers and instructional designers might scoff at SCORM: It’s outdated (replaced by CMI5 and xAPI); it reinforces the much-maligned “page-turner” approach and related instructional pedagogies; it forces learners and instructional designers to stay within the confines of the learning management system (a.k.a. the “walled garden”); it’s not secure; it requires the learner to use a web browser instead of engaging with the real world; yadda yadda yadda.

Those arguments certainly have merit. However, there’s no denying SCORM is deeply entrenched in the enterprise LMS world, and SCORM continues to be the primary format for corporate training courses. There’s a reason products like Articulate Rise and Adobe Captivate continue to generate millions of dollars in annual revenue.

As for why hand-coded, there are hundreds, if not thousands, of developers who need to understand how to build a simple SCORM course without being locked into a vendor’s ecosystem. Not everyone wants to use a rapid e-learning development app, and I’m often asked for help by small teams trying to build SCORM courses with modern development stacks such as React and Vue.

These tutorials are for them.

The tutorials will be structured linearly, with a goal of being less like a reference manual and more conversational in nature. The series will be an organic walk-through of concepts and exercises, progressing from simplistic to increasingly sophisticated. Key concepts are introduced within the context of exercises; each exercise builds upon the previous exercise, often reusing code snippets, so it’s a good idea to start with the first tutorial and work your way through each section.

By the end, you should be armed with the knowledge and tools you need to insert basic SCORM support into just about any HTML project.

I wanted to take Trax for a spin, so I installed it on a DigitalOcean droplet. My installation is configured for production (not limited to localhost) and includes a domain name and HTTPS. Here are the steps I used to install and configure Trax.

Create an Ubuntu Droplet in DigitalOcean

From your DigitalOcean account, click Create then select _Droplet_s. The Create Droplets page will appear.

Choose your region (I selected San Francisco), then choose Ubuntu. At the time of this writing, the latest long-term support edition is Ubuntu 24.04 LTS x64.

Droplet Size

To keep costs down, I selected a shared CPU with a regular SSD. If this were a true production system, I would have opted for a dedicated CPU. Trax LRS should work fine with the cheapest 2GB RAM package (50GB SSD, 2TB transfer). At the time of this writing, this configuration costs $12/month. The droplet specs can always be beefed up later if needed.

New to DigitalOcean? Use my affiliate link for $200 of free credit!

Authentication Method

The authentication method is up to you, but I use the SSH key option for convenience.

Finalize Details

Edit the droplet’s Hostname field to whatever works for you. This is just for your own reference within your DigitalOcean account. Click the Create Droplet button to complete the process.

Once the droplet has been generated, you will see its IP address in your DigitalOcean dashboard. Make a note of the IP address, we will need it in future steps.

Configure your domain name

Go to your registrar of choice (I use porkbun.com) and configure your domain as needed. Use the droplet’s IP address for the A record. I won’t be providing instructions for configuring the domain, as each registrar uses slightly different workflows.

Install Trax

Connect to the droplet via SSH and prep the system

SSH to your droplet using your terminal of choice (I use Warp) and your droplet’s IP address. For example:

ssh root@123.123.123.123

Note: For simplicity, this tutorial will be running commands as the root user. The best practice in Linux environments is to create an admin user on the system, SSH into the system as that user, then run the same commands, but prefixed with sudo. If you plan to use these instructions for a true production environment, please set up an admin account and avoid using root.

Once connected, ensure the system is up to date by running

apt update && apt upgrade

Install dependencies

Trax has a number of dependencies, including PHP and a database (I’m using MariaDB instead of MySQL). Install the dependencies using the following command:

apt install apache2 php libapache2-mod-php php-mysql php-curl php-xml php-mbstring php-zip php-gd mariadb-server git composer certbot python3-certbot-apache

Note: If this were a true production system, I would use a dedicated database server.

Harden MariaDB

For safety, let’s take a moment to secure the MariaDB installation.

Run the following command, then follow the prompts as needed. If you elect to configure a password for the MariaDB root user, be sure to write it down as you will need it later.

mysql_secure_installation

Install the Trax files

Grab the Trax files from its GitHub repository, then run the Trax install script.

git clone https://github.com/trax-project/trax2-starter-lrs /var/www/traxlrs
cd /var/www/traxlrs
composer install

Note: As previously mentioned, this tutorial is using the Ubuntu root account. If you’re following the tutorial step by step, you will see a warning about running composer as a root user. For this demo, it’s safe to ignore the warning. If you’re setting up a true production environment, you should not be using root.

Set permissions

Now that the Trax files and directories are in place, we need to ensure permissions are correct. I used the following configuration, though you may be able to lock it down further, if desired:

chown -R www-data:www-data storage bootstrap/cache
chmod -R 755 storage
chmod -R 755 bootstrap/cache

Configure Apache

There are several things that need to be configured for Apache. First, let’s configure the virtual host:

nano /etc/apache2/sites-available/traxlrs.conf

This will bring up the virtual host settings in the nano text editor. Insert the following snippet. Be sure to modify the ServerAdmin and ServerName fields for your environment:

<VirtualHost *:80>
    ServerAdmin admin@example.com
    DocumentRoot /var/www/traxlrs/public
    ServerName example.com
    <Directory /var/www/traxlrs/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Save the file and exit nano. (If you’re unfamiliar with nano, you can press control-x on your keyboard to exit, which prompts you to save changes. Type Y to save changes, then press Enter to save the file using the existing file name.)

Next, enable the site and rewrite module:

a2ensite traxlrs.conf
a2enmod rewrite
systemctl restart apache2

Configure the database

MariaDB was installed, but we haven’t set up the Trax database yet. Log in to MariaDB:

sudo mysql -u root -p

If you created a password for the MariaDB root user, enter it now.

You should see the SQL prompt in your terminal. Edit the following to use a proper password for ‘traxuser’, then paste into the SQL prompt and press enter.

CREATE DATABASE traxlrs CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'traxuser'@'localhost' IDENTIFIED BY 'YourSecurePassword';
GRANT ALL PRIVILEGES ON traxlrs.* TO 'traxuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Update the environment file

Trax comes with a sample environment file. It’s a great starting point, so let’s copy it, then edit it to fit our needs:

cp .env.example .env
nano .env

In the nano editor, update the file to reflect the latest info. Be sure to include your actual database password.

DB_DATABASE=traxlrs
DB_USERNAME=traxuser
DB_PASSWORD=YourSecurePassword

We’ll be coming back to the environment file in a moment. For now, save and exit.

Finalize Trax installation

Run the following commands to finalize the Trax installation:

php artisan key:generate
php artisan migrate

Let’s create a Trax admin account:

php artisan admin:create

Set environment to production

Since this is a public-facing installation and not running locally on your machine, we need to update the environment file to production values. Open the .env file again:

nano .env

Then update the following values:

APP_ENV=production
APP_DEBUG=false

Save and exit.

Optimize the installation

Run these commands to do some quick optimization:

php artisan config:cache
php artisan route:cache

Enable HTTPS

We’re almost done! The Trax system should be up and running, but we should ensure it’s using HTTPS. We’ll use Let’s Encrypt, which makes HTTPS easy. Run the following command then follow the prompts. Be sure to use your actual domain name, not example.com!

certbot --apache -d example.com

Once you’ve completed the certbot prompts, your Trax system should be up and running at your specified domain.

And, hypocritically, I am a strong proponent for ad blockers that prevent sites from tracking my visits.

Coupled with the increasingly poor Google Analytics administrative experience (more confusing, more bloated, overemphasis on monetization features I don’t need) and confusing support for GDPR, it prompted me to look for alternatives.

This isn’t the first time I’ve tried something else. Around 2014, I switched to Matomo (formerly piwik), an open-source self-hosted clone of Google Analytics. While it worked OK, it became too much to manage, and after a couple of years, I begrudgingly switched back to Google Analytics.

Now, nearly a decade later, I find myself wanting to untangle from Google again, and figured Matomo would be a mature solution worth revisiting. Unfortunately, Matomo is still heavier than I’d like. I don’t really want to self-host anymore, and Matomo was proving to be a bit complicated to integrate into Vue-based projects. I was also not looking forward to implementing new GDPR-compliant ‘click to consent to cookies’ prompts.

While researching Matomo, I ran across a discussion of plausible.io’s approach to privacy. I had never heard of Plausible, but was immediately impressed by their pitch: they’re based in Germany, and by default only collect anonymized data, meaning they’re GDPR compliant out of the box, and no ‘cookie consent’ prompts are required. While Plausible does get blocked by some ad blockers, its focus on privacy is helping them slowly get allow-listed by ad block vendors, meaning Plausible’s analytics scripts are less likely to be blocked than Google’s.

Plausible feels very reminiscent of Proton, a privacy-focused suite of products in Switzerland designed to help people decouple from Gmail. Like Proton, Plausible isn’t free, but that’s because they’re not scanning or selling your data. Both Proton and Plausible are very affordable, and the modest fees help them continue to provide the service. (Shameless plug: Here’s a referral link for Proton if you’d like to try a month of Proton’s Mail Plus for free!)

I signed up for a free 30-day trial of Plausible, and was impressed with the simplified dashboard and ability to import historical Google Analytics data. So much so that I immediately decided to switch platforms, moving this blog, PDFObject.com, and some of my other properties to Plausible.

Time will tell how wise the decision is, but I’m already enjoying the Plausible experience much more than Google Analytics. It’s more streamlined, and doesn’t nag me to monetize or integrate with an ad platform. Plausible supports funnels, goals, and campaigns if I ever decide to incorporate marketing into my sites, but by default is a nice bare-bones way to get site stats without compromising user privacy. And that alone makes Plausible worth a shot.

I’ve been playing guitar since I was a teenager in the late 80s, and got the bug for building guitars circa 2018. A chance encounter with a YouTube video gave me the crazy idea that instead of buying guitars, I should build them! My priorities immediately shifted: outside of my job and my time with my family, I used to mostly divide my time between playing guitar, working on code, or watching San Francisco Giants games (sometimes all three at once). Once I got into guitar building, I spent most of my free time watching videos and reading articles about building guitars. I would still write code and play with the latest tech, but at a much slower clip, hence the lack of posts on pipwerks.com.

(Shameless plug: Here’s a video documenting one of my guitar builds… I made a guitar out of an IKEA butcher block countertop!)

In December 2023, another YouTube video sent me down another rabbit hole: Chris Monck from Highline Guitars described his process for designing a guitar fretboard, which began in FretFind2D, and then moved to Adobe Illustrator, where he painstakingly re-drew the fretboard produced by FretFind2D. Being a developer, I knew it was possible to make a better SVG than what was being produced by FretFind2D, so I rolled up my sleeves and got to work.

Being an open-source project, my initial thought was to fork FretFind2D and improve the SVG and PDF handling. However, as I dug into the code, which was written back in 2010, there were simply too many things to fix, from outdated jQuery to inaccessible form fields and the odd bug. I found myself rewriting entire sections of JavaScript, wanting to modernize the code style, wanting to completely redesign the UI, and getting ideas for new features that would be difficult to implement in the FretFind2D environment. It became too much. I decided it would be a better use of my time to write a new system from scratch using a modern reactive framework.

(Note: This is not a knock on FretFind2D, which is still an amazing piece of work!)

I prefer Vue over React and Angular, so I started working in Vue 3. This would enable me to create a much better user experience, and would also give me hands-on time with the latest web technologies, including Pinia for state management and Tailwind CSS for styling. I also befriended Chat GPT and Claude.ai, who helped me with my questionable geometry and trigonometry skills.

This project took me much longer than anticipated; I easily spent over 150 hours over the course of a few months working on it. I was learning as I went — and I learned a LOT — but I was also constantly coming up with new ideas and features, many of which required additional research or rewriting swaths of code. In total, the project is about 14,000 lines of code spread over 91 files.

I’m very pleased with the result. The SVG is rendered by Vue, and is updated in real-time whenever the user tweaks parameters. The SVG can be downloaded as an SVG or PDF, and settings can be downloaded as JSON for future use. Some of my favorite features are outlined on the About page.

I usually release my projects as open-source, but I’ve decided not to open-source this one. It’s free to use at https://fretboard.buzz, but I’m retaining the copyright and deciding next steps. As always, I have a few ideas!

If you try the site and have any feedback, please hit me up on my Weekend Luthier Instagram profile.

There are quite a few improvements in 2.3, including switching to a pure iframe solution for more robust cross-browser support, and improved handling of PDF Open Parameters. See the changelog for more details.

I’ve also revamped pdfobject.com. It now features more thorough documentation and examples. Thanks to its new VitePress backend, it should load quickly and is fully searchable. The new Browser Support page goes into great detail about which browsers support inline PDFs, as well as a handy reference table for checking which PDF Open Parameters are supported in each major browser platform.