Friday, June 22, 2012

5 Tips For Using jQuery with WordPress

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 */
});

0 comments:

Post a Comment

I am a student of MS(CS), and also a computer software engineer and web developer.