Now that we understand the basics of jQuery and WordPress and have a little background on how they'll interact with each other, we're now ready to take a look at using jQuery to dynamically enhance a WordPress installation. We'll start with getting jQuery included in WordPress and end up with our first cool project: Expanding and collapsing content. This is only the beginning of the jQuery possibilities in store for your WordPress site! Again, we'll be using WordPress 3.0 in this title and the new default Twenty Ten theme with jQuery 1.4.2, but rest assured that if your site or project is still using WordPress 2.9, these jQuery techniques will work just fine.
In this chapter, we'll cover the following topics:
jQuery can be included into WordPress in three different ways as follows:
jQuery.com, and include it directly with a script tag into your XHTML header tags, inside your theme's header.php file (this method works, but is not really recommended for a variety of reasons)We covered the basics of the first method in Chapter 1, Getting Started: WordPress and jQuery. WordPress is so flexible that any user with the right admin level can come along and update, enhance the theme, or install additional plugins which may also use a version of jQuery or other JavaScript libraries. Therefore, including jQuery or any JavaScripts directly into the theme with hardcoded script tags is not recommended as it could cause conflicts with other scripts and libraries included into the WordPress site through theme customizations or plugins added to the WordPress installation. In this chapter, let's take a look at using the two remaining methods, registering jQuery through WordPress' Script API and using Google's CDN.
As of WordPress 2.7, jQuery and several other JavaScript libraries and plugins have been bundled and are available through WordPress' Script API through a handy function called wp_enqueue_script. Actually, WordPress has had jQuery and quite a few other JavaScript libraries (including Script.aculo.us with Prototype and many more) bundled into the wp-includes directory for some time, but until version 2.7, these includes were not so easily accessible.
You can activate WordPress' bundled jQuery in two different ways:
First, you can place the following code in your header.php file before the closing </head> tag:
<?php wp_enqueue_script("jquery"); ?>
<?php wp_head(); ?>
<script type="text/javascript">
//add jQuery code here
jQuery(document).ready(function() {
jQuery("p").click(function() {
alert("Hello world!");
});
});
</script>
Alternatively, you can register the wp_enqueue_script (and any custom jQuery code you write) in your theme's functions.php file. If your theme doesn't have a functions.php file, simply create a new file, name it functions.php, and place it in your theme's root directory with your other template files (functions.php is a standard template file that's included with the default theme we're using). Place the following code into your functions.php file:
<?php wp_enqueue_script('jquery');/*this registers jquery*/ function jq_test(){ /*This is your custom jQuery script*/ ?> <script type="text/javascript"> jQuery(document).ready(function() { jQuery("p").click(function() { alert("Hello world!"); }); }); </script> <?php } add_filter('wp_head', 'jq_test');/*this adds your script to the wp_head() hook in the header.php file and ensures your custom jQuery script is run*/ ?>
The first time that I ever attempted to load up jQuery using the wp_enqueue_script (both in the functions.php file and through the header.php file), I just could not get it to work. After some hair pulling and a few hours on the WordPress Codex, I finally realized the following facts:
header.php template file, make sure that the wp_enqueue_script function is above your wp_head function. Your custom jQuery code must go below the wp_head function.wp_enqueue_script in the functions.php file, make sure that it comes before any custom functions that load through the add_filter function into the wp_head.Read up on the wp_enqueue_script function!
This function is part of WordPress' Script API and it actually does a lot more than just load up jQuery! As I mentioned, there are many, in fact well over fifty, JavaScript toolkits, frameworks, user interface libraries, plugins, and helpers that you can load up safely using the wp_enqueue_script function. Check it out here: http://codex.wordpress.org/Function_Reference/wp_enqueue_script.
Personally, I am a little torn about registering and referencing the copy that comes with WordPress. I've discovered that loading the library from Google Code's Code Distribution Network (CDN) is sometimes a better way to go. The CDN saves on bandwidth, allowing your site to do some parallel processing while downloading other scripts and collateral. Plus, it's easy to always get the most current version of jQuery. jQuery's library loads very quickly from Google's CDN and, as a bonus, the library will already be cached if your site's user has previously visited another site that delivers jQuery from Google Code's CDN.
To include jQuery from Google Code's CDN, we'll be sure to deregister jQuery then register through Google's CDN. This is the beauty of registering and using the wp_enqueue_script function: if any other plugin or script requires jQuery, and doesn't have any conflicts with the version loading up from Google, that script will use the already loaded Google CDN library. If a script depends on a specific version of jQuery, say 1.3.2 or 1.2.6, and the CDN is loading up version 1.4.2, then that script will go ahead and load the version of jQuery it requires. Because (as we'll learn) every script loaded through the Script API stays in noConflict mode, it's OK to have the two library versions loaded as long as they're registered and required.
... wp_deregister_script( 'jquery' ); wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js'); ...
Google offers a great versioning system that allows you to be as precise as you want, or just pull the latest stable version. Consider the previous code example (note the highlighted number, 1.4, in the previous code example).
That previous registration script references version 1.4.2 of jQuery (the most recent version as of writing this title). When jQuery's developers release a new version, say, 1.4.3, that version will automatically be called by that same URL because I did not pinpoint the version's specifics. In the same vein, I could choose to call ...jquery/1.3/jquery... that would give me 1.3.2 the highest version in the 1.3 release. And you guessed it, targeting a simple ...jquery/1/... would pull the most recent version of jQuery, up to version 1.9.x, until jQuery turns over to version 2.0!
Generally, it's good practice to always have the most recent library load, but you never know, you may use a jQuery plugin or write some of your own code that doesn't work well with a newer version. You'd then want to target the last specific version of the library that works with your plugins or custom scripts, until you can fix and update them.
As I mentioned earlier, the wp_enqueue_script function allows for a safe load of jQuery (and other includes) into noConflict mode. As long as you deregister and register for jQuery from the Google CDN, the library will load into WordPress with the same noConflict mode protection. I really like to take advantage of Google's CDN, for the variety of performance reasons I mentioned, but for large projects with lots of editors and administrators making different decisions on how to manage the WordPress site and what WordPress plugins to use, I play it safe and register the bundled version into the theme. Also, for development, I find it nice to have jQuery already running locally on my MAMP or LAMP server, if I'm developing a theme and yet have disconnected from the Web due to traveling (or the need for enhanced productivity). Once a site is live, I'll consider switching it over to the Google CDN version of jQuery.