If you are a developer or designer working on Magento websites then you will likely have a need to use JavaScript to enhance its functionality and improve the customer experience by introducing dynamic interactive elements. Using an existing JavaScript library simplifies this process and can improve productivity. This post demonstrates the process of integrating the popular jQuery library into your Magento website. Magento already includes the Prototype JavaScript library, but integrating jQuery alongside Prototype allows you to have the best of both worlds.

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.

Comments

Thanks for your tip.
What i am doing for adding jquery is this:
1. In the root folder of magento installation there is folder js, in it i create another folder called jquery.
2. In root/js/jquery i put the jquery library and another javascript file jquery_functions.js cause from page.xml i see that it is using that folder name space to add the javascripts.
3. Make folder in app/design/frontend/default/ to represent your new theme, i call mine zoran and in it i create 3 folders (template, layouts and locale).
4. I copy the app/design/frontend/default/default/layouts/page.xml to app/design/frontend/default/zoran/layouts/page.xml. Just make sure you turn on this theme from the admin panel (with cache disabled)... How themes are organized, the page.xml will be loaded from the zoran folder cause it is higher in the hierarchy of the themes.
5. Add <action method="addJs"><script>jquery/jquery-1.4.min.js</script></action>
<action method="addJs"><script>jquery/functions.js</script></action>
 
after
mage/cookies.js

in the head section, cause this part is loaded on every page of magento it will add the jquery library and the jquery_functions.js files.
To test it, open jquery_functions.js and add this code:
var jq = jQuery.noConflict();
 
jq(document).ready(function()
{
alert('I am from jquery');
 
//or
//console.log('I am from from jquery');
});
Go to the frontend home page and refresh.

Thanks for letting us know about the alternative approach you've adopted.

Separating the jQuery.noConflict call from the main jQuery library itself is a good idea - makes it easier to wipe over previous copies of jQuery when upgrading to newever versions.

Also placing jQuery in the magento/js/ directory is good too. Although I'd stick to keeping custom jQuery code in the magento/skins/ directories as magento/js/ normally stores JavaScript libraries and widgets. Hence placing jQuery and any plugins into the magento/js/ directory is sensible but customisations for a specific website and presumably a particular theme should be stored in the skins directory, specific to the theme.

Thanks for the feedback!

Thank you for the answer Tom. I still haven't had time to play around more with the skin folder (since i am more of a developer than designer), but as i can see your answer makes pretty good point about keeping own JS files into the skin directory. I just want to avoid for some reason overriding the template files before the layouts, cause of the way Magento calls the theme. It first calls the layout which i would first extend, then it calls the templates which i would extend as a second option. It's like telling Magento: OK let me take the control from here. And the sooner you take the control in your hands the more options you will have. Please correct me if i am wrong, cause i have been using this technique a lot especially while dealing with CodeIgniter framework and it showed up as a good thing so far.
Thank you again!
Zoran

Just a short addition to your post...
I have upgraded to Magento 1.4 and in the admin panel System -> Configuration -> Developer -> The tab Javascript settings: Merge JavaScript Files (beta) should be set to No, otherwise if you try to add jquery it will throw an error and none of the previous loaded js files will work. Also you can still use the magento/js folder to add jquery in the page.xml file in the head section as i described it in my previous comment.

Thanks for sharing it.. your page helps me for jquery configration with magento

Thanks for your help. Finally i got answer from you. it works well now

Hi,

Is there anyone that could make some "blank" magento template or extension, that would work with the minimum or totaly without javascript?
Or if that is not possible, is there anyone who could make a magento default template using only jQuery with no prototype and other loads of scripts? I think that that could be quite popular template for a lot of developers.

kind regards
Jakub

It worked for me after I tried this below. I put the after the whole bunch of CSS and JS (<?php echo $this->getCssJsHtml() ?>) :

<?php echo $this->getCssJsHtml() ?>
 
<!-- adding jQuery -->
<script type="text/javascript" src="../../js/jquery/jquery-1.5.min.js"></script>
<script type="text/javascript">
//<![CDATA[
var $j = jQuery.noConflict();
//]]>
</script>
<!-- ************* -->