Using RequireJS With Sitecore

Sitecore + RequireJS

RequireJS is a JavaScript file and module loader. It implements the Asynchronous Module Definition (AMD) API to allow us to create JavaScript modules, explicitly state dependencies and natively load all JavaScript asynchronously.

Because of Sitecore’s unique architecture, we can have Sublayouts load only the JavaScript they needs. With RequireJS managing modules & their dependencies, this becomes a very powerful technique. We’ll unpack it all below.

The Setup

We use jQuery heavily and suspect most others do too. We’ll focus on how setup jQuery and RequireJS within Sitecore. There are some key-modifications to make it work well with Sitecore.

Github: Download Complete RequireJS Example

Below is file structure in our demo that’s relevant to RequireJS:

This is require.setup.js. This acts as our configuration file.

Now let’s look how this fits into some typical HTML.

Here we call Modernizr, load the RequireJS library, the load the configuration file. It is important these files are loaded synchronously. Notice that we are not yet loading any of our own JavaScript files.

We'll use Sublayout Driven JavaScript so each page only has the minimum JavaScript required.

Writing The Modules

A module is reusable chunk of JavaScript. Libraries for things like validations, carousels, tickers, tabs or data services make excellent modules.

We’ll write a simple device detection module and psuedo-code a slider module.

Here is our device detection module detect.js.

Make sense? Next, we’ll write a slider module slider.js that references the device detection module detect.js.

Lastly, we’ll create demo.js that loads the slider and binds some arbitrary clicks to invoke methods from slider.js

Use define() when you’re creating a module. Use require() for the JavaScript file the you will explicitly be loading in your page. (See the RequireJS’ API docs for more details).

Using Sublayouts To Add Our JavaScript

The only requirement is that demo.js loads after RequireJS and the setup file has loaded. You could get away with this:

But that means every page will load jquery, demo.js, slider.js and detect.js whether they use them or not. I'd rather not.

Because Sublayouts contain specific functionality in Sitecore, it makes sense for our Sublayouts to load the JavaScript.

We have an article written about that technique, but here is the relevant code. Hopefully it reads well enough for you follow.

In short, we have DemoContent.ascx.cs that uses a utility method in JavaScriptUtilities.cs to inject JavaScript into MainLayout.aspx.

Now we've tied our JavaScript files tightly to our Sublayouts. And with the module and dependency support we only need to add a single JavaScript file and RequireJS will manage the rest.

Closing Thoughts

In our opinion, writing modular JavaScript using RequireJS (or another AMD loader) is a must. And while not required, we’ve found injecting JavaScript via Sublayouts in Sitecore to be a very successful pattern.

It's very satisfying to reference a single JS file in the code-behind, simply add the corresponding Sublayout to a few templates and watch extremely rich client-side functionality pop-up all over the site.

I know this was a lengthy post - please leave any questions in the comments. I’d be happy to answer them. Thanks!

References:

RequireJS API: http://requirejs.org/docs/api.html
AMD JS API: https://github.com/amdjs/amdjs-api/wiki/AMD