Add a New Reference in Magento

If you already performed some Magento research, you will know that it is built on a fully modular model that gives great scalability and flexibility for your store. While creating a theme, you are provided with many content blocks that you can place in structural blocks. If you are not sure what they are, please read Designer’s Guide to Magento first. Magento provides few structural blocks by default and many content blocks. This article tells what needs to be in place to create new structural block.

What are structural blocks?

They are the parent blocks of content blocks and serve to position its content blocks within a store page context. Take a look at the image below. These structural blocks exist in the forms of the header area, left column area, right column…etc. which serve to create the visual structure for a store page. Our goal is to create a new structural block called “newreference”.

Step 1: Name the structural block

Open the file layout/page.xml in your active theme folder. Inside you will find lines like:

<block type="core/text_list" name="left" as="left"/>
<block type="core/text_list" name="content" as="content"/>
<block type="core/text_list" name="right" as="right"/>

Let’s mimic this and add a new line somewhere inside the same block tag.

<block type="core/text_list" name="newreference" as="newreference"/>

Good. Now we told Magento that new structural block exists with the name “newreference”. Magento still doesn’t know what to do with it.

Step 2: Tell Magento where to place it

We now need to point Magento where it should output this new structural block. Let’s go to template/page folder in our active theme folder. You will notice different layouts there. Let’s assume we want the new structural block to appear only on pages that use 2-column layout with right sidebar. In that case we should open 2columns-right.phtml file.

Let’s assume we wish the “newreference” block to be placed above the footer. In this case, our updated file could look like this:

<div class="main-container col2-right-layout">
            <div class="main">
                <?php echo $this->getChildHtml('breadcrumbs') ?>
                <div class="col-main">
                    <?php echo $this->getChildHtml('global_messages') ?>
                    <?php echo $this->getChildHtml('content') ?>
                </div>
                <div class="col-right sidebar"><?php echo $this->getChildHtml('right') ?></div>
            </div>
            <div><?php echo $this->getChildHtml('newreference') ?></div>
        </div>

Step 3: Populating structural block

We have the block properly placed, but unfortunately nothing is new on the frontsite. Let’s populate the new block with something. So let’s create new file app/design/frontend/[base]/[default]/template/newreference.phtml with the following content:

<h1 style="background-color:yellow">Hello New Reference!</h1>

Go to appropriate layout XML file (page.xml) and add this block to appropriate place (for testing purpose you could place it under “default” handle).

<reference name="newreference">
   <block type="core/template" name="newReferenceBlock" template="newReference.phtml" />
</reference>

Now if you visit your frontend you should see something like this:

Note, you could include any Magento block this way (you didn’t need to include our newly created:

<block type="core/template" name="newReferenceBlock" template="newReference.phtml" />

). Just be careful to do it properly!

Step 4: Add new reference in a proper way!

Sure that you’ll not modify Magento core files. Revert changes in page.xml and create local.xml file.

Inside of your local.xml file type something like this:

<?xml version="1.0" encoding="UTF-8"?>
<layout>
	<default>
		<reference name="root">
			<block type="core/text_list" name="newreference" as="newreference" translate="label">
				<label>New Reference</label>
			</block>
		</reference>
		<reference name="newreference">
			<block type="core/template" name="newreferenceblock" template="newreference.phtml" />
		</reference>
	</default>
</layout>

That’s it. I hope it will help someone 🙂

Note! This article was revised on Nov 26, 2012. by Ivan Galambos. You will notice that some of the comments are older. This is because the original article was posted in 2009.

In case you’re wondering how to improve the experience of your users even more, make sure to check out our UX & usability audit! it’s a perfect way to get a detailed insight into what would make customers love your store even more!