One of the best things about WordPress is its vibrant economy. For many users, it's trivially easy to find themes to fit the design for which they're aiming, or to find plugins that provide functionality that they want to introduce into their site.

But how many of you - as developers or designers - have a received that phone call or that email in which the customer claims that something is wrong with their site only to discover that the browser console displays something about an error having to do with JavaScript or jQuery?

Exactly. Most likely anyone who has built and/or maintained a site for someone has come across this problem especially if the end user is given permission to add their own plugins, allow their own updates, etc.

In this post, we're going to review a few concepts around jQuery and WordPress to make sure that we, as developers, are not only working to build our products correctly, but that we also know how to properly diagnose problems as they arise in our customer's sites.

A Word About Including JavaScript Files

This particular topic is not new to Wptuts+. In fact, we've written an extensive article about it before complete with a number of code examples all of which should provide you with everything that you need to understand how to work with JavaScript within WordPress.

But as we continue to observe certain practices going on in the community that we'd love to help resolve, we don't mind covering multiple facets of the same topic.

So, before reading this article, make sure that you're familiar with how to include JavaScript and CSS in your WordPress themes and plugins.

WordPress as a Foundation

When it comes to building products in WordPress, one of the things that we, as developers, need to try to do is to treat the WordPress application as a foundation.

Right now, the API allows us a massive amount of flexibility when it comes to building themes, plugins, and applications, and this is a good thing.

But when we begin to remove libraries that ship with WordPress in favor of our own, it's almost as if we're creating a "mini-fork" of the project.

This isn't a good practice to adopt.

As far as I'm concerned, WordPress ships with its core set of functions and libraries that allow it work the way that it does. Changing out crucial parts of the application - such as jQuery - doesn't only affect WordPress itself, but the entire ecosystem of products that are built on top of it.

Good themes and plugins depend on the presence of those libraries. When we change that functionality, we potentially break every piece of work that's depending on them.

We need to stop viewing WordPress as something that we can take apart and reassemble as we need it, and view it as a foundation off of which to build our own unique work.

Why the Problem of JavasScript Conflicts Exist

Generally speaking, the problem of JavaScript conflicts exist for one of three reasons. A developer has either:

1. Improperly managed jQuery in their code
2. Swapped the version of jQuery in favor of another version
3. Changed the order in which jQuery is loaded

First, any of the above three cases could all be done at once, but more often than not its one of the above. Secondly, I don't think that developers typically do this with ill-intent.

I think it's more of a lack of education and/or understanding of the consequences.

1. Improperly Managing jQuery

By this, I mean that the developer has improperly gained access to the jQuery library either by executing noConflict, not properly returning the variable to its original state, or simply renaming the short cut function.

Later in this article, we'll take a look at the best practice for how to write WordPress-specific jQuery so that it allows us to take full advantage of the library without conflicting with other plugins, themes, or projects.

2. Swapped Versions of jQuery

This is something that is often done with good intent: The idea is that the developer is providing an update to the version of jQuery that's included with WordPress so that new features or more modern jQuery can be written.

The problem with doing this is that previously developed projects aren't written with some of the newer features of the latest version of jQuery. Also, if jQuery has deprecated or completely removed a function in the new version that was present in the old version, then it will prevent that code from working.

3. Change the Order in Which jQuery Is Loaded

Though this is a less common problem, it's something that happens occasionally: In an attempt to help make a site load faster, developers will move the order in which jQuery is loaded further down the page, usually to the footer.

While loading JavaScript in the footer of a page is encouraged by a number of high profile sites, this goes back to thinking of WordPress, holistically, as a foundation for application development.

If WordPress, by default, loads jQuery in a certain location, then we need to remember to leave it there as all works that are built on top of the application are depending on it being in that location and nowhere else.

How to Properly Include jQuery

Though there are a number of different ways that you can prepare your JavaScript source files to use jQuery, there's one way that I tend to follow because it completely protects and encapsulates the $ function.

(function( $ ) {
	"use strict";

	$(function() {

		// Your code here

	});

}(jQuery));

You can also view the GitHub gist here.

In short:

This provides a properly loaded version of jQuery that uses the standard $ function reference to allow us to continue going about our work.

Note that the "use strict" statement provides the following:

Strict Mode is a new feature in ECMAScript 5 that allows you to place a program, or a function, in a “strict” operating context. This strict context prevents certain actions from being taken and throws more exceptions

For those who are interested, you can read more about that at this site.

Finally, the actual document.ready function is optional. Here, it's used just to show how you can begin using the standard jQuery functions within the context of the code.

Conclusion

Note that the next version of WordPress is planning to ship with a patch that will make this particular discussion obsolete, at least as far as the Dashboard goes.

Specifically, there is currently a ticket in Trac in which WordPress will not allow us to remove jQuery from the Dashboard. That's a good thing.

In short, the main takeaways for this article are as follows:

• Use the version that ships with WordPress
• Gain access to the $ function using proper JavaScript facilities

I'd say that doing anything else is setting yourself up for potentially bad results.