Installing jQuery

jQuery can be downloaded from jquery.com and to install it you need to copy the file to the following directory:

skin/frontend/default/your_theme/js

To include jQuery you need to edit layout/page.xml where you need to add the following to the head block:

<action method="addItem"><type>skin_js</type><name>js/jquery.js</name></action>

Normally, this would be all you need to do, however because Magento also includes Prototype, there is a subtlety we need to deal with. jQuery uses '$' as shorthand for accessing the jQuery library. But Prototype also uses '$' to access itself. This causes a conflict in the global JavaScript namespace of the web browser. Fortunately jQuery provides a solution, the jQuery.noConflict(); function defines a new shorthand for jQuery, such as:

var $j = jQuery.noConflict();

The above code needs to come after the jQuery library code, but before any other JavaScript libraries. You can include the noConflict call at the bottom of the jQuery file you have copied to the js directory. Therefore you need make sure that "action method" line we included in layout/page.xml comes before the code that includes Prototype or any other JavaScript libraries.

Google-hosted jQuery

Another method to use jQuery is to refer to the Google hosted version, by using the following code:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>

As the jQuery version is part of the URL, testing a new version is easy. The code should be placed into the head.phtml design template file (this is necessary as references to external URLs cannot be placed in the layout files of Magento):

app/design/frontend/default/your_theme/templates/page/html/head.phtml

Make sure that you include the code before this line:

<?php echo $this->getCssJsHtml() ?>

Also, remember to include the noConflict definition. Your customised head.phtml file should look something like this:

<title><?php echo $this->getTitle() ?></title>

<meta http-equiv="Content-Type" content="<?php echo $this->getContentType() ?>" />
<meta name="description" content="<?php echo htmlspecialchars($this->getDescription()) ?>" />
<meta name="keywords" content="<?php echo htmlspecialchars($this->getKeywords()) ?>" />
<meta name="robots" content="<?php echo htmlspecialchars($this->getRobots()) ?>" />

<?php echo $this->getChildHtml() ?>

<link rel="icon" href="<?php echo $this->getSkinUrl('favicon.ico') ?>" type="image/x-icon" />
<link rel="shortcut icon" href="<?php echo $this->getSkinUrl('favicon.ico') ?>" type="image/x-icon" />

<script type="text/javascript">
//<![CDATA[
 var BLANK_URL = '<?php echo $this->helper('core/js')->getJsUrl('blank.html') ?>';
 var BLANK_IMG = '<?php echo $this->helper('core/js')->getJsUrl('spacer.gif') ?>';
//]]>
</script>

<!-- adding jQuery -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript">
//<![CDATA[
 var $j = jQuery.noConflict();
//]]>
</script>
<!-- ************* -->

<?php echo $this->getCssJsHtml() ?>

<?php echo $this->helper('core/js')->getTranslatorScript() ?>
<?php echo $this->getIncludes() ?>

The benefit of using the Google hosted version is that there might be a performance improvement provided by the HTTP request being fulfilled by a local server that is part of Google's CDN, and if enough websites follow this approach then this JavaScript will be cached by browsers across these sites, resulting in minimal waiting time for a browser to load the core jQuery library.

The benefit of a self-hosted copy is that it can be combined with all the other JavaScript files in use on your site allowing for one single HTTP request to deliver all necessary JavaScript reducing the overhead introduced with individual requests. The other benefit is that there is no external dependence on the availability of the Google hosted version, even though it is unlikely to become unavailable.

jQuery Magento extensions

It should be noted that there is a third method of including jQuery in Magento that involves installing an extension. However, doing so can result in blocks being overwritten, which can potentially conflict with other extensions. As we have demonstrated, installing jQuery is not a difficult process, so it may be just as easy to include manually.

While Prototype is a great library in its own right, jQuery has led the pack in terms of performance in the web browser and ease of use. Developing with jQuery can be a faster experience than developing with Prototype, reducing the effort required to develop new JavaScript features for Magento websites.