Preventing jQuery conflicts in WordPress

Okay, it’s programming pet peeve time. Well, specifically web programming pet peeves. And really just one, so forget the plural there. Here goes nothing.

If you do any kind of web programming at all, you’ll have heard of jQuery, which is (according to this source: http://trends.builtwith.com/javascript/JQuery) the most popular Javascript library in use today. It’s got several things going for it. It’s powerful. It’s flexible. It’s easy to use. It’ll even clean your house and do your dishes if you ask nicely. OK, maybe not that last one, but I’m sure it will be in a future release.

Being as powerful as it is, it comes as no surprise that a large number of WordPress plugins use jQuery for all kinds of things. If you are a theme or plugin developer chances are you will frequently make use of jQuery in this development process.

The problem with so many developers using jQuery is using the traditional method of including it can cause conflicts between versions. Typically, you would load jQuery in one of a couple of ways.

If you have a local copy:

<script type="text/javascript" src="_js/jquery.js"> </script>

Or if you prefer Google’s CDN (Content Distribution Network) version:

<script type=”text/javascript” src=”http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js”></script>

The problem with directly placing these in your theme’s header, or using the add_action function as a plugin writer, is yours is likely not the only part of the end-user’s WordPress installation which will want to use jQuery. If you have multiple places in the website trying to load jQuery you end up with at best redundancy in your code and at worst a conflict which breaks your website.

Fortunately, if you want to use jQuery without causing conflicts then WordPress will do of the work for you. WordPress already includes its own version of jQuery, so if you’re happy with using the included version, all you need is this php function:

<?php wp_enqueue_script('jquery'); ?>

WordPress inserts all the queued scripts during the wp_head hook, so you need to call this function before that hook runs. If you’re a theme developer, it’s sufficient to insert this function call anywhere in your head section (assuming you follow the practice of always placing wp_head() at the end). If you’re a plugin developer, you’ll need to make use of the init hook.

<?php
	function my_init_method() {
		wp_enqueue_script('jquery');
	}
add_action('init', 'my_init_method');
?>

This will make sure the script is queued before wp_head is run. Now say you don’t like WordPress’s included version and would instead like to use a different version. Here is how you would change it to use the CDN version:

<?php
function my_init_method() {
	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', 'my_init_method');
?>

One last thing to note: WordPress loads jQuery in “no conflict” mode. A good description of the details of this mode are available here: http://api.jquery.com/jQuery.noConflict/. What this means for most users is just you’ll want to use the jQuery alias instead of the normal shortcut of $. This is to prevent conflicts with other scripts which use the same shortcut. Instead of looking like this:

$(‘.lameClass’).addClass(‘awesomeClass’);

Your code will look like this:

jQuery(‘.lameClass’).addClass(‘awesomeClass’);

You can see that WordPress has built in the capability to handle pretty much any scenario you could come across; you can even load different versions of jQuery and give them different aliases if you really need to. So now that everybody knows, I’m not going to see any more jQuery conflicts in WordPress. Right? Please?

You can find more information on queueing scripts and a list of plugins WordPress has handles for in the WordPress codex at http://codex.wordpress.org/Function_Reference/wp_enqueue_script.