WordPress Theme Lesson 11: Including Javascripts The Right Way

Our design doesn’t require much javascript, but it’s increasingly more common to use javascript to spice up a web design or for displaying dynamic content. For our theme we need to use jQuery for dynamic content on top of the front page, a slider with featured posts. You can improve more of the theme by using jQuery tabs, accordion menus, or to load content without requiring a page refresh. It can make the website more elegant, as long as you don’t overdo it.

If you’re creating a web page from scratch without a CMS, you’d just add each javascript library or script in the <head> section, like we’ve done with the stylesheet so far in this theme. But using WordPress as a CMS we need to take in consideration all scripts which might be added in the wp_head, scripts from both WordPress itself and all active plugins. This is why we need a safe way of adding scripts so that we don’t load the same libraries more than once, and that WordPress loads them in the right order. WordPress has a quite-simple-to-use mechanism for this.

Managing javascripts in WordPress is referred to as registering and enqueuing scripts, which is hooked onto a initializing state of WordPress. We register a script if it’s unknown to WordPress and enqueue it, which puts it in WordPress’ queue of scripts to load in either wp_head or wp_footer (remember wp_head and wp_footer from Lesson 2?). WordPress also takes care of preventing loading the same script twice. Let’s say some plugin and our theme loads the same library (e.g. jQuery UI), which means we have two enqueue-calls with the same library but the script will only be loaded once. If we didn’t use WordPress’ queue of scripts, it’s easy to risk loading a script twice, and most likely cause both scripts to stop functioning. We can also de-register a script, preventing it from being enqueued and included at all.

Update Aug. 6 2012: There is a right way to include stylesheets which works in a similar manner of scripts. Read the update on how to include stylesheets the right way.

Included with WordPress there’s a bunch of scripts, such as the core jQuery script and jQuery’s plugins. None of them are loaded as default, but we can choose which to load and when, without having a copy of the script files in our theme folder. See a list of all scripts included with WordPress here. The most interesting of them all is jquery, jquery-ui-core, scriptaculous, thickbox and tiny_mce (Tiny MCE is the text editor used in WordPress). Keep in mind that with libraries included in WordPress we only need to enqueue, not register them. It’s when we add our own script files we need to register them first, because they are unknown to WordPress (WordPress doesn’t know where it can find the files and what dependencies the script has).

An important note on jQuery: Keep in mind that WordPress loads jQuery in no conflict mode. What this means is that in your scripts you must use jQuery instead of the $ sign unless you assign jQuery into another variable.

NB:This whole lesson is code samples showing how we include scripts in WordPress and not something we are to do in our theme. We return to our theme in the next lesson, where we will use what we learned here.

Enqueuing WordPress-included Scripts

We do all the registering and enqueuing scripts in a function hooked onto the WordPress hook init. Hooking onto any other hook than init wil cause issues to arise.

We enqueue scripts using the WordPress function wp_enqueue_script(), with the script’s shorthand name defined by WordPress (the names are listed in the full list) as the first argument. The second argument is the file’s location, which we don’t need to provide with WordPress included scripts so we use null. The third argument is the script’s dependencies. Here we can tell which scripts we need to be loaded before this script can be loaded. For instance, if we want to load the jQuery UI library, we need to load the core jQuery library first, so we put jQuery as a dependency. Note that we don’t need to enqueue the jQuery core library if we’ve added it as a dependency. WordPress will automatically enqueue all scripts in the list of dependencies.

Let’s say we want to use the jQuery Tabs library, one of the scripts included in WordPress. It depends on the jQuery UI, which in turn depends on the core jQuery library. To do this, we only enqueue the jQuery Tabs using the shorthand name jquery-ui-tabs, and set jquery-ui-core and jquery as dependencies. We put the wp_enqueue_script() in a PHP function in our functions.php and hooks it into the init hook:

functions.php:

function wpthemetutorial_add_js() {
	if (!is_admin()) {
		wp_enqueue_script('jquery-ui-tabs', null, array('jquery', 'jquery-ui-core'));
	}
}
add_action('init', 'wpthemetutorial_add_js');

If you try this function and refresh and take a look on the source code of your site, you should see that jQuery, jQuery UI and the jQuery UI Tabs libraries are included. They normally resides in the footer where you put your wp_footer, and it will do so even if you add a False to the in_footer parameter. Sometimes they are being loaded in the wp_head hook in the <head> section. It’s really up to WordPress where the scripts are loaded.

You’ve probably noticed the if-check on is_admin(). With conditional tags we can choose which pages we want to enqueue scripts, preventing loading unecessary scripts where we don’t need them – in this case the WordPress admin interface. You could e.g. enqueue scripts only at a particular page template, or anywhere except the front page. To learn more take a look at the list of conditional tags.

And that’s how you enqueue a WordPress-included script. But what if you want to remove a WordPress-included script, and replace it with another file, such as an older or newer version?

Deregistering a WordPress-included Script

If you want to prevent a script to be included, or provide another file or URL to a WordPress-included script, you can deregister it with wp_deregister_script(). It’s used in the same way as wp_enqueue_script(), providing the shorthand name as the first parameter.

Perhaps a more common example of deregistering a WordPress-included script is when you of some reason want to use the CDN copy of jQuery instead of the one included with WordPress. In that case we deregister the jQuery script, register it again with the CDN URL, and finally enqueue it.

functions.php:

function wpthemetutorial_add_js() {
	if (!is_admin()) {
		wp_deregister_script('jquery');
		wp_register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js');
		wp_enqueue_script('jquery');
	}
}
add_action('init', 'wpthemetutorial_add_js');

Note that we’ve registered and enqueued it with the same shorthand name, jquery, making sure all dependencies on this library works normally.

Registering and Enqueuing Your Own Scripts Files

Now that we’ve been through WordPress-included scripts, let’s learn how we can include our own scripts. It could be a jQuery plugin not included in WordPress which we’ve copied into our theme folder, or a self-written script. In this case we must remember to register them before we enqueue it, so WordPress knows where to find the file. By registering a script we make up an unique shorthand name which we will then use when we enqueue it.

In this example we’ll include a script called wpthemetutorial.js which requires the jQuery core library being loaded first. It resides in a folder called js in the theme folder.

functions.php:

function wpthemetutorial_add_js() {
	if (!is_admin()) {
		wp_register_script('wpthemetutorial_js', get_bloginfo('stylesheet_directory') . '/js/wpthemetutorial.js', array('jquery'));
		wp_enqueue_script('wpthemetutorial_js');
	}
}
add_action('init', 'wpthemetutorial_add_js');

We register the script with the shorthand name wpthemetutorial_js and set the path as second parameter by getting the stylesheet directory and adding the rest of the path after it. The jQuery core library is its only dependency. We then enqueue the script by using the name we gave it when registering. And that’s it.

Adding Initializing Script Code in The <head>

When using jQuery libraries and plugins you often need to initialize functions on document ready, code which you normally’d place in the <head> section. The safe way to do this with WordPress is ensuring that libraries this code depends on are loaded first, e.g. the jQuery library.

We will hook our function onto the wp_head hook. The hook init which we’ve registered and enqueued all of our scripts are run before wp_head. This ensures that all libraries are loaded before we add our intializing script.

In the example below we assume we’ve enqueued the jQuery UI Tabs (the first example above). We need to initialize jQuery Tabs by calling the .tabs() function inside a jQuery document ready. So we create a PHP function which hooks onto the wp_head. Don’t forget the jQuery.noConflict().

functions.php:

/* Adds JS code to be run in <head> */
function wpthemetutorial_add_init_js() {
	?>
	<script type="text/javascript">
		jQuery.noConflict();
		jQuery(document).ready(function($) {
			jQuery("#tabs").tabs().tabs('rotate', 5000);
		});
	</script>
	<?php
}
add_action('wp_head', 'wpthemetutorial_add_init_js');

Back to Our Theme…

Hopefully these examples should help you understand the basics and be prepared when we need to add scripts to our theme later in this tutorial. We are going to add a jQuery slider for our featured posts in the next lesson, and for that we need to register and enqueue the CDN of jQuery Tools, with jQuery core as a dependency. We also also need to initialize the slider in the wp_head. I’ll show you the code in the next lesson, but I won’t explain it in depth.

If you tried out the above examples, remember to delete what you might’ve added in your functions.php in this lesson.

WordPress Codex Function references:

This concludes Lesson 11 of the WordPress Theme Tutorial. Go to the next lesson, Featured Posts, Dealing with Multiple Loops.