Wordpress, jQuery and ‘noConflict’

I’ve been working on a plugin for Wordpress and have, until now, been using Mootools. I decided that I should try and simplify things by using jQuery, since it is already included with Wordpress.

So let me take you through my links and hopefully summarize what I’ve learned. First though, let me say, I’m assuming that you already know what it means to hook into the Wordpress application flow by adding “actions”. If not, read up.

Inject Your Javascript

The Wordpress Codex for wp_enqueue_script has a list of other javascript libraries included as well as a link to this brief tutorial at Nick Ohrn.

Basically Wordpress provides the wp_register_script method to register a javascript file and its dependencies using a unique string to serve as a “handle”. After you’ve registered them, you can then use that handle when calling wp_enqueue_script. This will spit out the appropriate <script> elements to your document, in their correct order, and (hopefully) avoid any duplicate entries or conflicts with other scripts.

I’ve added both the wp_register_script and the wp_enqueue_script calls to the method I’ve added as part of Wordpress 'init' (i.e. add_action('init', myLoadJsMethod)). I think you can also just use wp_enqueue_script directly, without first registering, but it seems like a good idea to do both. For example, if things change, you can keep the registration in 'init' but then move the call to enqueue somewhere else, like the 'template_redirect'.

What’s important to know, though, is that you cannot call wp_enqueue_script as part of the 'wp_head' action. At that point, it’s too late. This was confusing to me because I was originally just echoing out the path to my script within the function I set for 'wp_head', and it worked fine. But to work within the Wordpress world, it has to happen before the header action, which means 'init' or 'template_redirect' (or possibly others, not sure).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

function my_init_method()
{
    // include the js if not a single post page
    if(!is_single()) 
    {
       wp_register_script(
       		'my_handle', 
                my_get_base_path() . "js/my_javascript.js",
                array('jquery')); // my_javascript.js depends on jQuery
 
       wp_enqueue_script('my_handle');            
    }    
}
 
function my_get_base_path()
{
    return get_bloginfo('url') . "/" . PLUGINDIR . "/" . plugin_basename("read-more-right-here/");
}
 
 
add_action('init', my_init_method);

Notice that at line #11 I only needed to use the string ‘jquery’ to register my script as being dependent on it. This is because ‘jquery’ is included with Wordpress and has already been registered with that handle.

Making jQuery Work

Let’s test this out with a simple call to alert in our javascript. Following good practice, we’ll make sure to do this after our page’s DOM is locked and loaded.

1
2
3
4

$('document').ready(function() 
{	
	alert("ready");
});

Ahh Crap. Firebug is telling me that $ is not a function. A little google later and I’m at this thread, with the answer I’m seeking nine messages in, right here.

jQuery in WordPress uses the noConflict option to prevent issues with
Prototype…….Check online for jQuery.noConflict()

It’s always something. Alright, so what do the jQuery docs say?

By default, jQuery uses “$” as a shortcut for “jQuery”. However, you can override that default by calling jQuery.noConflict() at any point after jQuery and the other library have both loaded.

It goes on to say that you can also just set something else as the new “$” by setting a new variable to the result of jQuery.noConflict().

So the above javascript is changed to this:

1
2
3
4
5
6

var $j = jQuery.noConflict();
 
$j('document').ready(function() 
{	
	alert("ready");
});

And it works!

Summation (Because I Type Too Much)

• Use wp_register_script and wp_enqueue_script to load your javascript
• Do not use wp_register_script and wp_enqueue_script as part of the wp_head hook, it must happen earlier (e.g. init, template_redirect)
• jQuery in Wordpress uses “no conflict” mode, see here for workarounds

If I’ve misstated or completly misunderstood anything above, please feel free to correct me in the comments.