Having used jQuery and WordPress together on a number of plugins and
themes, I thought I'd share some tips that I have learned. The following
are 5 clear, concise, and relevant tips that you should know when using
jQuery in your WordPress Theme or Plugin.
1. Use wp_enqueue_script()
The traditional way to include jQuery in an HTML page is with the
script
tag. When working with WordPress, you should *never* do this. To avoid
conflicts and other potential problems, you'll want to load jQuery using
the following code:
function my_init() {
if (!is_admin()) {
wp_enqueue_script('jquery');
}
}
add_action('init', 'my_init');
You can replace
my_init with something more meaningful,
but choose a unique name to avoid conflicts. For plugin development, add
the code in your plugin file, otherwise, add this code to your theme's
functions.php file. The
is_admin() check is to prevent script queuing on your admin pages.
WordPress References:
2. Load jQuery from the Google AJAX Library
Since WordPress includes jQuery, calling
wp_enqueue_script('jquery'); will automatically load the jQuery file located in
wp-includes/js/jquery/jquery.js.
If you want to load jQuery from the
Google AJAX Library, you'll need to modify the code as follows:
function my_init() {
if (!is_admin()) {
// comment out the next two lines to load the local copy of jQuery
wp_deregister_script('jquery');
wp_register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js', false, '1.3.2');
wp_enqueue_script('jquery');
}
}
add_action('init', 'my_init');
There are a
number of reasons
why you would want to use the Google AJAX Library to load jQuery, but
remember, Google has been down before, so be ready to comment out the
first two lines if necessary.
Note: As mentioned by Milan in the comments, there are existing plugins, such as
Use Google Libraries, that will do this for you.
3. Load jQuery in the footer
Using the code in the previous two tips, jQuery will, by default, be inserted into the
head of your HTML page. If you would prefer to have jQuery inserted at the bottom of your page, you'll need to use the
$in_footer parameter for the
wp_enqueue_script() function. The modified code:
function my_init() {
if (!is_admin()) {
wp_deregister_script('jquery');
// load the local copy of jQuery in the footer
wp_register_script('jquery', '/wp-includes/js/jquery/jquery.js', false, '1.3.2', true);
// or load the Google API copy in the footer
//wp_register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js', false, '1.3.2', true);
wp_enqueue_script('jquery');
}
}
add_action('init', 'my_init');
As with the choice to use the Google AJAX Library, there are
reasons why you'd want to load jQuery at the bottom of your page. Note: if a script is loaded using
wp_enqeue_script() that lists jQuery as a dependency and has
$in_footer set to
false, WordPress will place jQuery in the
head instead of the footer, regardless of the
$in_footer value for jQuery.
4. Add jQuery as a dependency
You've got jQuery loading and now you want to include a script that uses it. This is where the
wp_enqueue_script() function really comes in handy. By passing an array of dependencies for the
$deps parameter, WordPress will automatically manage the order and placement of your
script tags.
For example, if you have a JavaScript file in your theme that
leveraged jQuery, the following code would ensure that your file is
loaded correctly:
function my_init() {
if (!is_admin()) {
wp_deregister_script('jquery');
wp_register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js', false, '1.3.2', true);
wp_enqueue_script('jquery');
// load a JS file from my theme: js/theme.js
wp_enqueue_script('my_script', get_bloginfo('template_url') . '/js/theme.js', array('jquery'), '1.0', true);
}
}
add_action('init', 'my_init');
The previous code example would load jQuery from the Google AJAX
Library, place it in the footer of your page and then include your
theme.js file. The
$deps array allows for multiple dependencies and helps you manage the scripts that are loaded on your site.
5. Proper jQuery coding conventions
All of the previous steps are nullified if proper jQuery coding
conventions aren't followed. The most common issue I see with jQuery and
WordPress is the misuse of the
$ variable.
It is important to know that the version of jQuery that comes with WordPress automatically calls the
jQuery.noConflict(); function, which gives control of the
$
variable back to whichever library first implemented it. If you are
loading a different copy of jQuery, you'll need to manually call
jQuery.noConflict();, if necessary, from one of your JavaScript files.
As a general rule, you should not use the
$ variable for jQuery unless you have used one of the
shortcuts. The following is an example of how to shortcut jQuery to safely use the
$ variable:
jQuery(function ($) {
/* You can safely use $ in this code block to reference jQuery */
});