Recently I’ve been digging into require.js a lot – a JavaScript library that conditionally loads external elements (like plugins or libraries) based on need. It’s been a great tool to have in my front-end toolbox, as it allows me to call up plugins only when I need them, thus increasing the performance of the site that I’m working on as well as minimizing the potential of running into conflicts or bugs from scripts not written by myself.
It’s been fine for local, flat development because the folder and URL structure of these initial builds is always fairly predictable. However, using require.js with a WordPress build can be a little more tricky as your URL and directory structure may become a little more unpredictable, but there is a quick and easy workaround that allows you to use this invaluable library in your project.
Before we get in to including require.js in your WordPress build, let’s take a look at what require.js is and how it works:
Require.js is a JavaScript library which allows a developer to reference external javascript files conditionally within another javascript file. This method is preferred to calling the file in the DOM as it reduces the number of HTTP requests (thus reducing page load time), ensures the proper load order for files and methods, and can help reduce unintentional run-ins with plugin or library code that may conflict with your own. So how do you use it?
After the obvious step of downloading the library, you’ll want to reference it in your HTML like any other JavaScript file:
<script type=“text/javascript” src=“js/require.js”></script>
In your custom file (which for the purposes of this demo we’ll call functions.js) you’ll need to tell Require where to find your external plugins or scripts. Lets say that within your “js” directory you have a subdirectory named “plugins” where you keep all your jQuery plugins Configure the constructor function in your “functions.js” file like such:
require.config({
baseUrl : "js/plugins"
});
Once this is set, any time you call the function “require” the script will know to look in your “plugins” subdirectory, and you can begin to load your plugins.
Let’s assume that I have a slide on my homepage, and I need to call the method “slider” to initialize the function. I would then start the slider after the page loads like this:
require([‘slider.min’], function() {
$(‘.slide’).slider();
});
Let me explain what’s happening here:
1) First we’re referencing the primary function, “require” – essentially “telling” the script that we’d like to conditionally load an external file using our previously configured settings.
2) We are then telling Require that we want to load the file “slider.min.js”. The file reference within an individual require function appends the file extension “.js” without user input, so “slider.min” will load “slider.min.js”, “jquery” will load “jquery.js”, and so forth.
3) We are then beginning the callback function, which is wrapped around our slider method.
4) We’re calling the slider method, attaching it to the element $(‘.slide’)
As you can see, this ensures that when we want to load our slider plugin we only have to call it once in the JavaScript file that we’re referencing it in – much cleaner and simpler than conditionally loading it via PHP, and faster than an HTTP request.
So how do we use it in a WordPress build? The challenge is in config method – because of the dynamic nature of WordPress, a theme or plugin developer does not know where the CMS will be installed in relation to the root directory, so files must be referenced absolutely. As a result, we have to use wp_localize_script function.
In your functions.php file, call up the function like this:
$my_js_dir = array( ‘path’ => get_stylesheet_directory_uri() . ‘/js' ); wp_localize_script( ‘my-dependent’, ‘my_variable_reference’, $my_js_dir );
Employing this function will tell WordPress to print a JavaScipt variable before your dependent file is enqueued and printed (using the wp_enqueue_scripts function) which you can thus reference in your functions.js file (or wherever you configured require). The variable is printed as an object like such:
var my_variable_reference = { path : “http://mysite.com/wp-content/themes/my-theme/js” };
so in your functions.js file you’ll change your require.config method to look like this:
require.config({
baseUrl : my_variable_reference.path + “js/plugins"
});
require.js will now look for your plugins via the absolute URL, and you’ll be ready to load external files directly in your JavaScript.
Do you have any preferred ways of including JavaScript files in your WordPress sites? Or do you have any followup questions about using require with WordPress. Leave your questions in the comments section below.
