Just jQuery

Just jQuery includes the wonderful jQuery JavaScript library for other plugins to use.

Download →

If you have a nice and simple site then you should just be able to download the plugin and go. Feel free to ignore the rest of this page. :)

If you have a more complicated setup (with many plugins and JavaScripty bits) then you may want to read on. The reason I’ve put the library into a separate plugin is to allow more flexibility in cases like this. Specifically, Just jQuery allows you to:

• Include jQuery only once for all your plugins
• Get jQuery working alongside other libraries on your site

Unfortunately you may need to do some work yourself too before that happens. The remainder of this article gives an overview of why you may have problems and some things you can do about it.

A quick aside

As the rest of this page is devoted to discussing problems, I should probably mention a couple of things. The first is that you’re unlikely to have difficulties. The second is that, even though libraries like jQuery do introduce some complications of their own, they also bring huge benefits to developers and users alike.

So what’s jQuery?

jQuery is a JavaScript library that provides all sorts of useful functionality for making web pages more responsive and interactive. (Seriously, it’s pretty amazing stuff – give it a go.) Consequently, quite a few WordPress plugins and themes use jQuery and other JavaScript libraries, giving you a suitably snazzy website.

But unfortunately they can interfere with each other too, with sometimes hard-to-diagnose results. Specifically, there are two problems:

• Different versions of jQuery interfering with each other
• Other libraries interfering with jQuery

Redeclaring functions

If you redeclare a JavaScript function, only the second instance will be accessible to other code on your site. In the best case you will just have wasted bandwidth by forcing everyone to download it twice, but you may have more serious issues if the behaviour of the two functions is different.

Quite a few JavaScript libraries like to use $ as shorthand to call many of their functions. This makes for compact code, but if a plugin written for one library ends up actually calling the other because the $ has been reassigned, the result will be an ugly error, not a pretty animation.

The problem may be more subtle if you include two different versions of jQuery on your site. jQuery is frequently updated, and new functions are added regularly (and occasionally deprecated too). So you may find that most of a plugin’s code works fine, but certain aspects – ones that rely on a new function call – fall over unexpectedly. All calls to jQuery are being passed to the old library, not the new one the code was expecting.

A good way to check for this sort of conflict is simply to disable the other plugins on your site and see if things start to work again. You may also want to use the superb Firebug to pinpoint exactly which plugins are including what.

Using jQuery included with another plugin

If you already have a plugin or theme that uses jQuery, you will probably be good to go and don’t need Just jQuery. That said, you may have issues if the version of jQuery included with that plugin is older (or newer) than that expected here.

If things aren’t working or you’re getting JavaScript errors then try updating the jQuery library. (This will probably be called jquery.js – make sure you rename the downloaded replacement to whatever the original file was called.) You may also want to check out the section on editing your plugins below.

Using Just jQuery instead of a plugin’s jQuery

To do this, you’ll need to find the line in the plugin’s source file that includes jQuery and comment it out. Open the code in a text editor and run a search for jquery.js (or whatever the library’s called in that plugin). You will probably be faced with a line a bit like this:

<script type="text/javascript" src="<?php bloginfo("url"); ?>/js/jquery.js"></script>

Comment out the line like this:

<!--<script type="text/javascript" src="<?php bloginfo("url"); ?>/js/jquery.js"></script>-->

Upload the modified plugin to your site and you should be good to go. (Of course you may not be if you accidentally comment out the wrong bit or need to use PHP, rather than HTML, comments. Always make a backup… :)

Other libraries and jQuery

There are quite a few JavaScript libraries out there that offer similar functionality to jQuery, with Moo Tools and Prototype / script.aculo.us perhaps the most popular alternatives. As mentioned just above, these libraries have an unfortunate propensity to interfere with each other, and the most common problem is appropriating the $ variable.

The no conflict option forces jQuery to restore the $ to its original owner, hopefully allowing the libraries to coexist peacefully. (Though note that if you have jQuery code that relies on $ it will break. If you replace $ with jQuery it should work again; for instance $("p.Toggle").click becomes jQuery("p.Toggle").click.)

Just jQuery has a checkbox in WP admin to enable no conflict mode.

Plugin priority

For the no conflict option to restore the $, it must first have been appropriated by another library. If the other library is included in your theme’s header, make sure the line that includes the library, something like

<script type="text/javascript" src="conflicting-library.js"></script>

is above the line

<?php wp_head(); ?>

in header.php.

Alternatively, if the library is included by another plugin, that plugin must be called before this one. However, it is important for this plugin is called before any other plugins that rely on the jQuery library. The order should be:

Conflicting plugin → Just jQuery → jQuery plugins

By default, WordPress plugins have a priority of 10. Those with lower values are called earlier. Just jQuery has an option to change its priority; I’d recommend setting it to less than 10.

Editing your plugins

If you still have issues after playing around with these options, you may need to edit an offending plugin to bump up its priority a bit. Back up the file, then open it in a text editor and look for a line that begins add_action("wp_head"…

The third parameter is the one in which we are interested, and may or may not be present already. If not, just add it on the end. So if you wanted to alter a plugin’s priority from 5 to 1, you would change

add_action("wp_head", "some_plugin", 5); to

add_action("wp_head", "some_plugin", 1);

And to change a plugin from the default (10) to a priority of 5, change

add_action("wp_head", "some_plugin"); to

add_action("wp_head", "some_plugin", 5);

Upload the plugin to your site again and you’re good to go.

Huh?

I know this is a very cursory overview of how to get jQuery and other libraries working together, and I’m a little worried that it will only make sense to those who know how to do this sort of thing already. If you’re still having problems (there are, unfortunately, plenty of other reasons why it can go wrong too), you could try asking a question below and I’ll see what I can do. No promises, though… :)