Adding jQuery to Magento

Question

What is the recommended way to add jQuery (or any script) BEFORE the rest of the scripts that come with Magento using local.xml?

I've tried to use (in local.xml):

<reference name="head">
    <action method="addItem">
        <type>skin_js</type>
        <script>js/jquery-1.6.4.js</script>
    </action>
</reference>

but this ends up adding jQuery to the end of the scripts that are added by Magento in page.xml in the base package. I've even tried removing all the scripts using:

<action method="removeItem">
...
</action>

to remove all of the scripts that were added in page.xml and then re-adding them in local.xml in the order I need them to be in (jQuery first), but somehow, they are ending up in the same order (with jQuery last).

I've stepped through the Magento code and verified that the scripts are getting removed and then re-added to $this->_data['items'] in Mage_Page_Block_Html_Head, but at some point, when they get added to the page, they are added with jQuery last.

I'm guessing there has to be a more elegant way to do this, but I've yet to find it in my Googling. Everything I've found recommends modifying page.xml directly, which I've read elsewhere is not a good idea.

Answer 1

My preferred (and the most flexible way) to do this is through XML using local.xml, two separate Javascript files, and a new file we will create. The first Javascript file is jQuery itself--completely unmodified. The second file I call no-conflict.js and it contains only one line:

jQuery.noConflict();

Now we add both of these files, along with a new block, to the head section of our local.xml:

    <reference name="head">
        <block type="page/html_head" name="topScripts" template="page/html/top_scripts.phtml" before="head">
            <action method="addItem">
                <type>skin_js</type>
                <name>js/jquery-1.7.2.min.js</name>
            </action>
            <action method="addItem">
                <type>skin_js</type>
                <name>js/no-conflict.js</name>
            </action>
        </block>
    </reference>

no-conflict.js is necessary to allow jQuery to work alongside Prototype, the Javascript framework included in Magento by default. Keeping jQuery and a no-conflict file separated allows you to upgrade or downgrade jQuery as needed without the need to edit the jQuery file itself to include the noConflict() method.

In our XML we created a new block (topScripts) with the template file set to top_scripts.phtml.

Navigate to /app/design/frontend/PACKAGE_NAME/TEMPLATE_NAME/template/page/html/ and create this new file. It will contain one line:

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

Now edit /app/design/frontend/PACKAGE_NAME/TEMPLATE_NAME/template/page/html/head.phtml.

Find the line <?php echo $this->getCssJsHtml() ?> in your head.phtml and add this line directly above it:

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

You have now correctly added jQuery before any other Magento Javascript.