Magento Themes and Magento Extensions

Creating a Magento layout block


Magento is a tricky beast to layout correctly. It makes use of not only template files and XML files to fit everything together. The documentation is a little vague (because they offer no support unless you buy the license), but by reading enough forums and blog posts (like this one), you can piece it together.

The goal

I’ve got a site design that has a “toolbar” that displays on all pages. It’s not in the sidebar and it’s not in the header. It’s inside the main content section, floating up at the top. I need to create the toolbar, and then put the Magento site search and Magento cart summary in that toolbar.

Some background

The Magento templates are comprised of “blocks”. There are structural blocks and content blocks. Structural blocks dictate what the different sections of the site are (i.e. header, footer, sidebar, content, etc.), while content blocks dictate what goes into those sections.

Where to put it

Because this “toolbar” is a piece of content, I thought it’d be best to stick it inside a pre-exisiting structural block. I thought that block would be the “content” structural block (not a content block, but a structural block named “content”, but I looked through the template file to verify.

I wouldn’t dream of modifying the original template, so I’ve copied it over and am modifying the copy to make my own. The site is a 2-column layout with the sidebar on the left, so app/design/frontend/custom/default/template/page/2colums-left.phtml is my base.

Looking through the template file, I see the “content” structural block, but before it there a the “breadcrumbs” block. Hmm, that means the breadcrumbs are not inside the “content” structural block. That means the breadcrumbs content block is inside its own structural block. Interesting.

Well, I want my toolbar to go before the breadcrumbs, so I obviously can’t put my toolbar in the “content” structural block. What do I put it inside of?

Nothing, there is no other structural block to use. I decided I would have to create my own structural block and put my toolbar content in there.

Building the content

I started by copying the breadcrumbs file (the file that actually renders the breadcrumbs) to make the toolbar code.


copied over to


. . . and I just filled it with a <div> and some dummy content.

Then I modified the main template file (2colums-left.phtml) by adding a method to call the toolbar right before the method to call the breadcrumbs.

<div id="main">
    <!-- start toolbar -->
    <?php echo $this->getChildHtml('toolbar') ?>
    <!-- end toolbar -->
    <!-- start breadcrumbs -->
    <?php echo $this->getChildHtml('breadcrumbs') ?>
    <!-- end breadcrumbs -->

I hoped it would be as simple as that, but no, it didn’t show my toolbar.

Modifying the layout XML

I’ve noticed that app/design/frontend/custom/default/layout/page.xml seems to be a rather important XML layout file, so I opened it up. I found the line where the “breadcrumbs” structural block is defined and I copied it over to create a “toolbar” structural block. I don’t know how the “breadcrumbs” structural block works, but I couldn’t get the template block to work without defining a template attribute

<block type="page/html_breadcrumbs" name="breadcrumbs" as="breadcrumbs"/>
<block type="page/html" name="toolbar" as="toolbar" template="page/html/toolbar.phtml"/>

Now the toolbar shows up when I reload my page. Nice.

Real content in the structural block

I want to add the Magento cart summary and the Magento site search to the toolbar. First I have to modify the toolbar template file to look for its modules. The file app/frontend/custom/default/template/page/html/toolbar.phtml contains nothing but this now:

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

That tells it to look for modules that are referring to it – in this case, referring to “toolbar”.

Now I just have to modify some modules so they refer to the toolbar. First the cart summary.

The cart summary is located in app/design/frontend/custom/default/layout/checkout.xml. I only have to change the reference attribute. It was modified to look like this:

. . .
    <!-- Mage_Checkout -->
    <reference name="top.links">
        <block type="checkout/links" name="checkout_cart_link">
            <action method="addCartLink"></action>
            <action method="addCheckoutLink"></action>
    <reference name="toolbar">
        <block type="checkout/cart_sidebar" name="cart_sidebar" template="checkout/cart/sidebar.phtml"
            <action method="addItemRender"><type>simple</type><block>checkout/cart_item_renderer</block>
            <action method="addItemRender"><type>grouped</type><block>checkout/cart_item_renderer_grouped
            <action method="addItemRender"><type>configurable</type><block>checkout/cart_item_renderer
. . .

Now I do the same thing for the site search. It’s located inapp/design/frontend/custom/default/layout/catalogsearch.xml. Again, I only have to change one line. It now looks like this:

. . .
    <reference name="toolbar">
        <block type="core/template" name="" as="topSearch"
    <reference name="footer_links">
        <action method="addLink" translate="label title" module="catalogsearch"
            <label>Search Terms</label>
            <url helper="catalogsearch/getSearchTermUrl" />
            <title>Search Terms</title>
        <action method="addLink" translate="label title" module="catalogsearch">
            <label>Advanced Search</label>
            <url helper="catalogsearch/getAdvancedSearchUrl" />
            <title>Advanced Search</title>
. . .

Comments are closed.