Packaging JavaScript Interactives

Background

At CTL, client-side interactives enrich many of our serial-learning web applications. These discrete JavaScript blocks challenge students with quizzes, animations, case studies, calculators and games. The goal is to transform a passive reading exercise into an active learning experience. The interactives encourage students to use higher-order skills to deepen understanding and aid retention.

Our in-house content management tool Pagetree provides the framework for our interactives. The JavaScript blocks hook into the content hierarchy using well-known patterns. The Pagetree infrastructure is a powerful and cost-effective approach when user data must be collected and analyzed. But, many of our interactives carry enough context to stand on their own statelessly. Our clients often want to make this class of content available in blogs, wikis and social media. Our developers began exploring a way to make this happen years ago, but failed to find a reasonable solution. I was recently re-tasked with finding a way to make this happen.

Research

Luckily, we’re now not the only ones who want to organize, share and reuse JavaScript code. JavaScript build and release tools have matured and proliferated. npm organizes code into packages, and offers a repository for those packages. On install, npm downloads the package code and its dependencies. Webpack is a module bundler that can package both scripts and other assets such as stylesheets and images. Browserify, Require.js, jspm.io, rollup.js are similar module bundlers. The Web Components standard offers a way “to create reusable web components that include both HTML and JavaScript.” The choices are now overwhelming. Here are just a few comparisons to review: 1, 2, 3.

In considering the options, I decided the Webpack module bundler was the best fit due to these winning features:

1. Custom loaders. Our interactives need static data, images, stylesheets and clientside templates. The interactives rely on libraries like jQuery, Backbone.js and Bootstrap. Webpack’s custom loaders integrate all these things. A single line of code loads a json blob into a Backbone collection. Another line applies styles to the document. Easy.

2. Development server. Webpack includes a local server with hot reload capabilities. The bundle is rebuilt and reloaded in the web page as code and assets change.

3. One tool. Other tools require ancillary tools such as Grunt, Gulp, Bower and Babel to do all the things Webpack does. Dealing with just a single tool is quite appealing.

Implementation

My first implementation targeted an existing interactive in PASS, a website to educate pre-doctoral dental students about patient populations. The interactive demonstrates support services commonly available to older adults.

The code, templates and static assets transferred over directly. The src/index.js loads the required libraries based, applies the stylesheet and creates the view. The webpack.config.js governs how the various file types are loaded.

Package Structure

npm and Webpack do not dictate a standard package structure. After a little research, I came up with this based on our needs.

  project  
  |-- dist  
  |   |-- bundle.js  
  |   |-- *.svg, *.eot, *.woff*, *.ttf  
  |-- node_modules  
  |-- src  
  |   |-- index.js  
  |   |-- app-specific.js  
  |-- static  
  |   |-- css  
  |   |-- img  
  |   |-- json  
  |-- test  
  |   |-- test.webpack.config.js  
  |   |-- model-test.js  
  |   |-- view-test.js  
  |   |-- view-test.html  
  |-- Makefile  
  |-- index.html  
  |-- package.json  
  |-- webpack.config.js  

Makefile

Anders, a senior developer here, composed Makefiles for our Django projects. I wanted to do the same here for consistency. The pack’s Makefile can build the bundle, run the dev server and publish the project. Per our team’s standards, jshint and jscs are also run.

Static Data

Many of our interactives rely on a database for static data. That data is usually fetched directly from the server and loaded into a Backbone collection. To replicate this flow, I generated a json file via Django’s dumpdata method. The json file was then loaded into the Backbone collection.

Summary

The interactive migration coalesced into a published package with minimal pain. Our long-term goal is to create an interactives gallery to allow our work to be reviewed and embedded. For now, I’m on to a more complex interactive migration to validate this approach.

Look for a second post on composing and running unit tests and browser tests for a Webpack.