Add a New Reference in Magento (structural blocks)

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.

It will be helpfull.

Please share your comments