Magento Quickies

All the Non-Trivial Magento Trivia

Posts tagged layout

0 notes

Handlebars JS in Magento

In response to a retweet of adam_webdev by kalenjordan

Magento’s flexible layout system makes adding a javascript library like handlebars a cinch.

First, download the latest version of handlebars and drop it in your root javascript folder

js/handlebars-v1.3.0.js 

Next, add the following to your local.xml file.

<layout>
    <!-- this adds the javascript to the page.  This needs to be in a layout update xml -->
    <default>
        <reference name="head">
            <action method="addJs"><script>handlebars-v1.3.0.js</script></action>
        </reference>        
    </default>

    <!-- this adds a handlebars template to the page. It does not need to be
         in layout update XML file, we're putting it there for convience -->
    <cms_index_index>
        <reference name="content">
            <block type="core/text" name="example_handlebars_template">
                <action method="setText"><text><![CDATA[                    
                    <script id="entry-template" type="text/x-handlebars-template">                
                        <div class="entry">
                          <h1>{{title}}</h1>
                          <div class="body">
                            {{body}}
                          </div>
                        </div>
                    </script>
                ]]></text></action>
            </block>
        </reference>
    </cms_index_index>
    <!-- this adds a prototype js dom:ready listener to replace the body content
         with our template.  This does not need tobe in a layout update XML file         
         we're putting it here for convenience -->

    <cms_index_index>
        <reference name="content">
            <block type="core/text" name="example_handlebars_usage">
                <action method="setText"><text><![CDATA[                    
                    <script type="text/javascript">
                        document.observe("dom:loaded", function() {
                            var source = $('entry-template').innerHTML
                            var template = Handlebars.compile(source);
                            var context = {title: "My New Post", body: "This is my first post!"};
                            var html    = template(context);
                            $($$('.col-main')[0]).update(html);
                        });                    
                    </script>
                ]]></text></action>
            </block>
        </reference>
    </cms_index_index>         
</layout>

Only the first <default/> is actually required to be in a layout update XML file. The two <cms_index_index/> handles are used to

  1. Add a handlebars template to the page

  2. Add a simple init script to the dom:ready event, showing how you might use the library with Prototype JS.

Also, the <default/> node doesn’t need to be in local.xml — you could create you own Magento module, use it to add a custom layout update XML file, and add the addJs call there.

Assuming you theme’s CMS index page has a div with the class .col-main, the above code sample will replace the main content of the homepage with a rendered handlebars template.

If you’re unfamiliar with the Magento layout terms above, you may be interested in my Magento for PHP MVC developers series of blog posts, or my book No Frills Magento Layout.

Filed under magento handlebarsjs layout

19 notes

Adding Additional Layout XML Updates via Modules

Update: Turns out the previous post was missing a <layout> tag in the code examples. This has been fixed, and we regret the error. (Thanks to Bartosz Cisek, proprietor of brillan.pl, for the correction)

I was surprised to discover I hadn’t covered this anywhere other than No Frills Magento Layout.

The XML files in a theme’s layout folder

[package]/[theme]/[layout]

are Layout Update XML files. They’re all loaded into a single file called the design package.

If you want to add your own XML file, you’ll need to add a Magento module. Once you’ve added a module to the system, you’ll need to configure the name of the Layout Update XML file you’d like added.

To do this, first add the following node to your module’s config.xml file.

<config>
    <!-- ... -->
    <frontend>
        <layout>
            <updates>
            </updates>
        </layout>
    </frontend>
</config>

The <updates> node is where you configure the XML files Magento will load the design package. Next, add a uniquely named node that identifies your update

<config>
    <frontend>
        <layout>
            <updates>
                <packagename_modulename>
                </packagename_modulename>
            </updates>
        </layout>            
    </frontend>
</config>

If you use a node name already in use by another Magento module (ex. <catalog/>), one node will get lost in the shuffle. Finally, add a <file/> node to specify which file you’d like loaded

<config>
    <frontend>
        <layout>
            <updates>
                <packagename_modulename>
                    <file>packagename_modulename.xml</file>
                </packagename_modulename>                
            </updates>
        </layout>
    </frontend>
</config>

Magento will now look for a packagename_modulename.xml and if found, include its updates in the design package.

If you need to add an XML update file to the admin console application, you’ll want everything located under the <adminhtml/> node

<config>
    <adminhtml>
        <layout>
            <updates>
                <packagename_modulename>
                    <file>packagename_modulename.xml</file>
                </packagename_modulename>                
            </updates>
        </layout>
    </adminhtml>
</config>

Filed under magento php layout

5 notes

Order of Block Creation in Layout Updates

This one might be greek to people who haven’t read No Frills Magento Layout, but I’d like it spelled out so I don’t have to think about it again. (If you don’t own a copy, there are worse ways to learn Magento).

When Magento is loading handles from the Layout Update XML Files into the package layout, these updates are loaded into an internal array, handle by handle. All the handles from one file are loaded, and then handles from the next file are loaded. The core.xml file is first, the page.xml file is second, etc. This ordering will be significant.

More significant is the order of the handles.

default
STORE_default
foo_baz_index
customer_logged_out

When generating the Page layout, the Layout_Update object searches through the Package layout, by handle. This means (in the above example) all the default handles are loaded first, then the STORE_default, etc.

The local.xml Layout Update XML File is always loaded last. That’s to ensure a store developer has a simple place to put all their layout updates that will ensure they’re loaded last and “win” over core layout updates. However, just because the updates in local.xml are loaded last does not mean that any update added to local.xml will run after an update in another file.

An update added with a <default> handle in local.xml will run before an update added with a STORE_default handle in page.xml. (The page.xml is the first file loaded).

That’s because, irrespective of the file they’re in, default handles are all added to the Page layout first, which means their meta-code will run first.

Filed under layout update magento no frills magento layout greek