Importing JavaScript libraries for complex SSJS in Squiz Matrix

Since version 5.4 of Squiz Matrix, server-side JavaScript (SSJS) has been available for templating purposes. However, at first glance it appears quite limited. This tutorial shows you how to add external libraries to your SSJS code for more complex implementations.

Basic usage

SSJS code can be run in Content Containers, Paint Layouts or Design files. To start using it, simply use script tags like this:

<script runat="server">

print("hello world");

</script>

JavaScript functions are fine, so this will work as expected:

<script runat="server">

function sayHelloWorld() {
  return "hello world";
}

print(sayHelloWorld());

</script>

However, this will only get you so far, and soon the limitations of vanilla JavaScript rear their heads.

Importing libraries

However, it is straightforward to import libraries such as Underscore or Mustache to create much more sophisticated implementations. Let’s take Mustache as a simple example.

First of all, add Mustache to your system by creating a JS File asset anywhere you like. Download Mustache.js from Github and upload it to the file asset or paste the code directly into the Edit file screen.

Now add the following keyword to your SSJS code block (where 999999 is the asset id of the JS file you created):

<script runat="server">

// import mustache.js
%globals_asset_file_contents:999999%

</script>

Now you can take advantage of the templating capabilities of Mustache within your Squiz SSJS code.

Example

The following example demonstrates how to create a simple masthead. By using Mustache we can keep our data and HTML separate for cleaner and more readable code.

<script runat="server">

// import mustache.js
%globals_asset_file_contents:999999%

// get the asset id for the section
// usually this would be done via a Squiz keyword but is hardcoded here for simplicity
var sectionId = '123456';

// create a data object to pass to Mustache
var mastheadData = {
  "title": '%globals_asset_attribute_name:' + sectionId + '%',
  "url": '%globals_asset_url:' + sectionId + '%',
  "colour": '%globals_asset_metadata_section.colour:' + sectionId + '%',
  "imageUrl": '%globals_asset_metadata_section.masthead.image:' + sectionId + '^as_asset:asset_href%'
}

// create a template to pass to Mustache
var mastheadTemplate = '<header class="masthead" style="background-image: url(\'{{imageUrl}}\');background-color:{{colour}};"><div class="container"><div class="row"><div class="span12"><a class="masthead-title" href="{{url}}">{{title}}</a></div></div></div></header>';

// render the masthead to a variable
var mastheadHtml = Mustache.render(mastheadTemplate, mastheadData);

// print the masthead wherever you need it
print(mastheadHtml);

</script>

A note about scope

It’s worth mentioning that when Squiz Matrix renders the server-side JavaScript out, it is all combined into one script. This means that Mustache only has to be included once and it can then be used by any of your SSJS code blocks at render time. It is not necessary to include Mustache in every set of <script> tags.