Luminis: Forcing CSS/JavaScript Updates to Clients

[[innerindex]]

Introduction

I gave a talk at SunGard Summit in Anaheim this spring on Plymouth State‘s portal (myPlymouth). There were a number of really great questions that came up following my presentation, one of which is the topic of this post:

“How do you force a client’s browser to always use the correct version of CSS and/or JavaScript in Luminis?”

When upgrading Plymouth State’s Luminis installation from III to IV, we had to tackle this same issue and after banging my head against the wall a number of times, I found our answer. I wanted to:

Ensure that the JavaScript and CSS that is being served up to our users can be cached by their browser in order to optimize their download speeds.
Control when a user’s browser has to re-download a new version of the code.
Do the above within the bounds of the very restrictive caching provided by the Luminis product.

All of it was super easy to do, although I must admit I knocked my head against the wall a few times coming up with the solution to the 3rd in that list.

Step 1: Basic Browser Caching

When I sat down to tackle this problem, I knew that the inline JavaScript within nested_tables.xsl was an unforgiving issue – if I wanted to make a change to some of the inline JavaScript, those changes would not be forced upon the users until Luminis decided to let go of its cached nested_tables.xsl.

That didn’t work for me. So I ripped the inline styles out and combined a few JavaScript files into one…called combined.js.

My header within the regularLayout template in nested_tables.xslnow looked something like this:

<head .......>
   <title>.........</title>
   <script type="text/javascript" src="/js/clientsniffer.js"></script>
   <script type="text/javascript" src="/js/util.js"></script>
   <script type="text/javascript" src="/psu/js/combined.js"></script>
   <script type="text/javascript" src="/psu/js/behavior.js"></script>
   <link rel="stylesheet" type="text/css" href="/psu/style.css"/>
</head>

The files clientsniffer.js and util.js are SunGard delivered and I did not touch those two. As I mentioned before, I yanked out all the inline JavaScript (provided by SunGard) and dropped that into combined.js along with a number of jQuery code. Our own custom Luminis JavaScript that controls a lot of our Ajax-like functionality in myPlymouth is in behavior.js. And of course, style.css holds the CSS for our portal.

All of these files could now be cached by users’ browsers. Yay. I bounced the development portal and saw my changes in all their glory. Life was good.

Step 2: Browser Cache, Code Changes, and You

Invigorated by my recent success of effectively doing nothing, I grabbed a soda and began tackling the next objective. I had done this numerous times in my PHP applications and it was as simple as placing a version number at the end of the URLs used in the link and script tags. As such:

<head .......>
   <title>.........</title>
   <script type="text/javascript" src="/js/clientsniffer.js"></script>
   <script type="text/javascript" src="/js/util.js"></script>
   <script type="text/javascript" src="/psu/js/combined.js?v=1.0.0"></script>
   <script type="text/javascript" src="/psu/js/behavior.js?v=1.0.5"></script>
   <link rel="stylesheet" type="text/css" href="/psu/style.css?v=1.0.5"/>
</head>

Once again, I bounced our portal, saw the changes, and danced around the room. Step 2. Accomplished.

Step 3: Taming Versioning/Cache Expiration in Luminis

The goal of taming this versioning/cache expiration was to do so without the need for bouncing the portal so I could make changes on the fly without planning for down times. Step 2 – as I detailed above – only gets you so far. With Step 2 in place, I could easily make a change in my CSS file and edit nested_tables.xsl to one-up my version number. But, because nested_tables is cached by Luminis, that wasn’t good enough. Here’s what I came up with:

I removed the script and link tags in the header of the regularLayout template in nested_tables, created a file called load.js, and dropped the homeless script/link tags as document.writes in load.js…as so:

Start of a Solution: load.js

document.write('<script type="text/javascript" src="/js/clientsniffer.js"></script>');
document.write('<script type="text/javascript" src="/js/util.js"></script>');
document.write('<script type="text/javascript" src="/psu/js/combined.js?v=1.0.0"></script>');
document.write('<script type="text/javascript" src="/psu/js/behavior.js?v=1.0.5"></script>');
document.write('<link rel="stylesheet" type="text/css" href="/psu/style.css?v=1.0.5"/>');

But wait…

This gave me a file with all of my script/link tags and their appropriate versions. However…I couldn’t simply replace all those script/link tags with a script tag that pointed at load.js because load.js itself would be cached by users’ browsers. So this got past the Luminis caching, but not our end users. So I came up with this:

Final Solution: pre_load.js

So…I wanted to cache all my sub-files and prevent load.js from caching so that I could version my scripts easily without bouncing the portal. The solution? Yet another file! I called it pre_load.js and it looks something like this:

document.write('<script type="text/javascript" src="/psu/js/load.js?nocache=' + (new Date()).getTime() + '"></script>');

A simple document.write of a script tag with an appended variable based on time in order to prevent caching on the browser side. Yup…load.js is never cached, but it is a small price to pay.

Now my header in the regularLayout template in nested_tables.xsl looks like this:

<head .......>
   <title>.........</title>
   <script type="text/javascript" src="/psu/js/pre_load.js"></script>
</head>

How it works

Luminis happily caches the pre_load.js script tag in the nested_tables.xsl.
The JavaScript within pre_load.js writes another script tag to the document at render time. That script’s URL is a call to load.js along with a variable that changes each page load thus preventing load.js from being cached.
load.js then document.writes the appropriately versioned script/link tags into the document.
The individual script/link tags load the associated JavaScript/CSS files. If the browser has already cached that script/link URL (remember, we change the version numbers when we make changes to the JS or CSS), then the cached file is loaded…otherwise the new version is retrieved from the server.

Summary

The set-up is fairly basic but the results just what we were hoping! And all it took was:

Placing inline JavaScript into a file (combined.js)
Creating load.js to document.write script/link tags
Creating pre_load.js to document.write a script tag that uses a cache-free URL call to load.js

To date, we have not had any reported issues with local or server-side caching of our JS/CSS files using this method! You just need to make sure you remember to version your URLs in load.js!