RequireJS Guide

The Home Junction Membership plugins have utilized RequireJS to optimize script loading since 2014. RequireJS allows for javascript and CSS file loading asynchronously and on-demand. The Membership plugin initializes the RequireJS library, registers some common scripts needed for most projects and provides a simple API for using or extending the script library.

Registering Scripts

Registering RequireJS Scripts the WP Way

To keep things simple and familiar for WordPress developers, registering a script with RequireJS is as simple as enqueuing or registering a script as you would for any WordPress project with a few things to note.

// Typically you'll want to just register the script
wp_register_script('myscript', $script_path . '/my-script', array('require-js'), '1.0', true);

// But technically you could enqueue it as well... 
wp_enqueue_script('myscript', $script_path . '/my-script', array('require-js'), '1.0', true);

In the example above we are registering a script with WordPress in the usual way. There are 2 key things to note about the script registration above...

We've left off the .js part of the file name in the script path. The reason for this is because with how RequireJS is setup, the .js file extension is assumed.
The dependancy array contains require-js as it's a dependency.

Script Dependency

By setting a script dependency as require-js Membership will automatically remove the script from the standard WordPress enqueue process and add it to the RequireJS configuration. This means that the script you registered will not load (even if you use wp_enqueue_script) during the normal WP script loading process. Instead, you'll need to require it from within another script.

Registering Scripts the Membership Way

You can also register a script using the Membership plugin API...

use hji\membership\Membership;

/**
 * We run this against the `init` hook so that it loads early enough
 */
function registerRequireJs()
{
    $requireJS = Membership::getInstance()->requireJs;
    $requireJS->addPath('myscript', $script_path . '/my-script');
}
add_action( 'init', 'registerRequireJs' );

Loading Scripts

To load a script registered with RequireJS you'll need to load it from another script. This script can be enqueued in the standard WP fashion, itself loaded with RequireJS or even embedded in the DOM of the page. The Membership plugin namespaces the require command as hji.require to avoid issues with 3rd party libraries and scripts.

Example Require Call

In the example above we have registered a script with myscript as it's handle. In order for us to load that script on the page, we'd run the following Javascript on the page in question...

// async load the my-script.js file (see above)
// then execute a callback after it's loaded
hji.require(['myscript'], function() {
    // do something cool after the script loads...    
});

You can also require multiple scripts by adding additional handles to the require array....

hji.require(['myscript-1', 'myscript-2'], 'callback_function');

Trouble Shooting

Because of the nature of RequireJS and async script loading, it can become very easy to experience "race conditions" which cause JS errors and things start to break. For example, you can run into issues with jQuery-UI because the UI library can be registered as RequireJS AMD modules. The right way to do things is to register the jQuery-UI modules with RequireJS and let Require handle the loading process. But we're working with WordPress and can't (or shouldn't) deviate with how things are loaded because we need to keep compatibility with 3rd party plugins.

If you're loading a script that can be loaded as an AMD module and it isn't registered with Membership's RequireJS script paths, you should ensure that your script loads before RequireJS is loaded on the page. The handle for the Membership RequireJS library is require-js. There are a few ways you can resolve loading order issues...

Register your script with RequireJS using the wp_register_script method and load your logic within the hj.require callback. (preferred)
Register your script with RequireJS paths using the PHP method and enqueue the script without a require-js dependency. This method could still cause race condition errors.
Monkey with the registration of the Membership require-js script enqueue so that your script can load first. This isn't a great way to do things because you'll have to re-enqueue the Membership require-js script after your script is enqueued. And if HJI ever changes how we're enqueueing the script, your website may break.
Dequeue the require-js script, enqueue your scripts and then enqueue require-js again.