jQuery Checklist

jQuery is, in my opinion, the best javascript library out there. With the help of jQuery I have been able to deliver elegant solutions that range from utter simplicity to minimalistic complexity – and it all happens without any cost to user experience.

But even jQuery can be challenging when we don’t take the necessary steps to make sure it will work optimally. In this article I will go through a short checklist, that explains how to load your jQuery in the most fool-proof way.

Make sure the jQuery library is being loaded before any custom jQuery

As with any other javascript library, jQuery has to be loaded before one can start using it. It can be a good idea to check if jQuery is already present in your system before you include the library. jQuery is, for instance, already present in many WordPress themes.

<?php
	/* Always include wp_head() before the closing </head>
	 * tag of your theme, or you will break many plugins, which
	 * generally use this hook to add elements to <head> such
	 * as styles, scripts, and meta tags.
	 */
	wp_head();
?>
	<script type="text/javascript">
		// check if jQuery is already present/loaded
		if(jQuery) {
			alert("jQuery library is loaded!");
		}
	</script>
</head>

If jQuery library is already present, you will get a browser alert where it stands “jQuery library is loaded!”. In that case you don’t need to load the library again, but if you don’t get an alert box with this message you will have to include the jQuery library manually. You can do that by doing the following:

<?php
	wp_head();
?>
	<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery.min.js"></script>
</head>

The file name will vary depending of the version you’ll be using, but for a production site I’ll always recommend to use the “minified” version (look for “min” in the file name). That will keep your bandwith lean and load the library faster. You also have the option to load jQuery libraries provided by CDNs (Content Delivery Networks). Click here for an updated list of CDNs providing jQuery libraries. Below are some examples, you will only need one of them:

<?php
	wp_head();
?>
<?php // Google CDN ?>
	<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<?php // Microsoft CDN  ?>
	<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.6.2.min.js"></script>
<?php // jQuery CDN (via Media Temple) ?>
	<script type="text/javascript" src="http://code.jquery.com/jquery-1.6.2.min.js"></script>
</head>

Avoiding conflict between jQuery and other javascript libraries

Sometimes you will notice that even though jQuery is working as it should, a slideshow based on another javascript library stops working – or vice-versa. This happens because of a conflict among two or more javascript libraries.

jQuery has a very handy way of avoiding conflict with other javascript libraries (Mootools and Scriptaculous, etc.). By using jQuery “noConflict”, you will be avoiding some of the most commom conflicts among these kind of libraries, which often use the same symbol ($) to invoque their functions.

<script type="text/javascript">
	// this line avoids conflict with other javascript libraries using "$"
	jQuery.noConflict();
</script>

That will solve most problems, but to be on the safest side, it is considered a good practice to use “jQuery” instead of “$“.

It is a good practice to include “jQuery.noConflict();” in every page you’re using jQuery in, for the sake of future compatibility. It should load immediately below the jQuery library itself, before any jQuery plugin or jQuery custom script is loaded.

If you still experience conflicts after taking these precautions, make sure that all 3rd-party jQuery code is using “jQuery” instead of “$“. If after taking these all these measures you still experience a non-responsive jQuery script, make sure that the loading order for jQuery is correct. Then have a look at your syntax.

Load jQuery plugins after the jQuery library, but before any custom jQuery

Plugins can be a great way to simplify tasks, by shortening the code necessary to trigger certain behaviors you wish to use often. It is a good practice to load jQuery plugins between the jQuery library and your own custom jQuery scripts.

<?php // UI Tools: Tabs, Tooltip, Scrollable and Overlay (4.05 Kb) ?>
<script type="text/javascript" src="http://cdn.jquerytools.org/1.2.5/tiny/jquery.tools.min.js"></script>

It can also be smart to include a plugin only on the pages that require it to be loaded, by wrapping the includes within conditions on either PHP or on jQuery itself.

Load your own custom jQuery scripts

Now that you have taken all the precautions to make sure jQuery will load and function in the expected way, it is time to load your own custom jQuery scripts. It is considered to be good practice to load javascript by including external files, like so:

<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery-custom-includes.js"></script>
<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery-custom-links.js"></script>
<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery-custom-toggles.js"></script>

Though it would be even better to merge these files into one, whenever possible:

<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery-custom.js"></script>

Even though good practice determines that it is better to include jQuery through external files (like the one mentioned above), sometimes our variables are determined by values fetched from databases or through PHP calculations. In that case we need to use inline jQuery. The script will then look just like a javascript script, but have the syntax of jQuery:

<script type="text/javascript">
jQuery(document).ready(function() {
	// do your thing
});
</script>

Load your custom jQuery ONLY after the document has rendered

jQuery relies mostly on elements that need to be loaded before it can execute. Let us take an example:

jQuery('div.learning').hide();

In the jQuery above, all the divs with the class “learning” are getting the “display:none” CSS property. But if the divs with the class “learning” haven’t been fully rendered by the time the jQuery is triggered, it could mean that some of the divs with the class “learning” – if not all of them – will not get the “display:none” property and therefore still show after the document is fully rendered.

To avoid that, make sure that every jQuery script, be it external or inline, are invoked within the function below:

jQuery(document).ready(function() {
	// do all your magic here!
});

Wrapping it up

Below is everything put together (comments are within PHP so that they don’t render in the markup). Note that this applies for WordPress, but would be just as usable for other systems.

<?php
	wp_head();
?>
<?php // jQuery CDN (via Media Temple) ?>
	<script type="text/javascript" src="http://code.jquery.com/jquery-1.6.2.min.js"></script>
<?php // this line avoids conflict with other javascript libraries using "$" ?>
	<script type="text/javascript">
		jQuery.noConflict();
	</script>
<?php // UI Tools: Tabs, Tooltip, Scrollable and Overlay (4.05 Kb) ?>
	<script type="text/javascript" src="http://cdn.jquerytools.org/1.2.5/tiny/jquery.tools.min.js"></script>
<?php // custom jQuery ?>
	<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery-custom.js"></script>
<?php // custom inline jQuery ?>
	<script type="text/javascript">
		jQuery(document).ready(function() {
			// do all your magic here!
		});
	</script>
</head>

I hope you enjoyed it! This article is meant for beginners, but I’m sure I’ll find myself visiting it often enough!

1 Comment

  1. Alan
    Jan 14, 2012

    Thanks so much! I always spend hours trying to get a script to work because of sloppy process. This will help. It’s bookmarked. Thanks!

Submit a Comment