99% of the times I'm asked to debug jQuery code on WordPress sites. 99% of the times there are errors in the code. 99% of the times jQuery-based WordPress plugins generate conflicts with the theme in use. 99% of the times the code is procedural. 99% of the times the code is without comments. Time to stop.
Let's start from the very beginning: WordPress encapsulates a copy of jQuery (usually the latest one) throughout its environment. This means that calling jQuery methods directly raises JavaScript errors.
Solution: wrap all your code within a self-executing function, thus creating a sandbox:
(function($) {
// all your code goes here
})(jQuery);
Secondarily, plugins often overwrite the current jQuery version used by your theme, especially if they are obsolete or badly written. For that reason, always check your plugin's code to see if this is the case.
If so, try to remove the jQuery version used by your plugin using comments:
// obsolete jQuery version
// wp_register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js', '1.4');
// wp_enqueue_script('jquery');
This should prevent conflicts between different jQuery versions from happening. If your plugin (e.g. a slideshow) now stops working, it simply indicates the fact that its code is tailored to the jQuery version you've previously removed. It's time to search for a more modern plugin.
Another thing to consider is when you decide to write your own code. In this case, you basically need two files:
- a copy of jQuery
- your custom script
jQuery must come first, then your custom script. To include jQuery, you can choose between the built-in version hosted by your WordPress installation and your own copy. To use the built-in version, simply write the following code in your functions.php file within your theme (if not already present):
function add_scripts() {
wp_enqueue_script('jquery');
}
add_action('wp_print_scripts', 'add_scripts');
On the contrary, if you want to use your own copy of jQuery, you must to deregister the built-in version first:
function add_scripts() {
wp_deregister_script('jquery');
wp_register_script('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js', '1.8');
wp_enqueue_script('jquery');
}
add_action('wp_print_scripts', 'add_scripts');
If your own copy is hosted on your server or within your theme, use:
function add_scripts() {
wp_deregister_script('jquery');
wp_register_script('jquery', get_template_directory_uri() . '/js/jquery.js', '1.8');
wp_enqueue_script('jquery');
}
add_action('wp_print_scripts', 'add_scripts');
Now you need to register your custom script. Since your script depends on jQuery, you need to specify an additional parameter when using the wp_register_script() function:
function add_scripts() {
wp_deregister_script('jquery');
wp_register_script('jquery', get_template_directory_uri() . '/js/jquery.js', '1.8');
wp_enqueue_script('jquery');
wp_register_script('custom', get_template_directory_uri() . '/js/custom.js', array('jquery'), '1.0');
wp_enqueue_script('custom');
}
add_action('wp_print_scripts', 'add_scripts');
The same procedure applies when you want to register a jQuery plugin:
function add_scripts() {
wp_deregister_script('jquery');
wp_register_script('jquery', get_template_directory_uri() . '/js/jquery.js', '1.8');
wp_enqueue_script('jquery');
wp_register_script('carousel', get_template_directory_uri() . '/js/jquery.carousel.js', array('jquery'), '1.5');
wp_enqueue_script('carousel');
wp_register_script('custom', get_template_directory_uri() . '/js/custom.js', array('jquery'), '1.0');
wp_enqueue_script('custom');
}
add_action('wp_print_scripts', 'add_scripts');
Always remember this order:
jquery.jsjquery.plugin.jscustom.js
You can invoke your plugin within your custom script. There's no need to add additional <script> tags within your document. When using a jQuery plugin on a WordPress site, just make sure that the targeted element actually exists in your document structure:
(function($) {
$(document).ready(function() {
// Is there at least a lightbox to show?
if($('a.lightbox').length) {
$('a.lightbox').lightBox();
}
});
})(jQuery);
If you don't run this check, you'll get a JavaScript error when the target element is not present within your page.
Finally, sometimes you need to modify the JavaScript code of your WordPress theme. First you need to locate the main script used by your theme. Usually this file is contained within the JavaScript folder (usually named js) of your theme.
The problem is that many themes don't keep HTML and JavaScript separated, so you have to look through your theme files to locate these additional scripts. This is due to the fact that theme options are often used to generate the parameters passed to certain scripts (e.g. slideshows).
When you modify the main JavaScript file of your theme, always remember to create a backup copy of this file, just to be on the safe side. Use a JavaScript validator to make sure that your code doesn't contain syntax errors.
If you don't know the jQuery plugins used by your theme, run a search on Google to understand how they work and how you can configure them. Then you can modify the default JavaScript behavior of your theme more easily.
