Magento — Add Custom Structural Block Reference

Magento is built on a modular model, which gives the software a lot of flexibility in terms of layout and scale. One such example of this is the ability to create new structural blocks. Magento provides some structural blocks by default and many content blocks, which can be placed inside structural blocks. If you are not familiar with this concept, you can brush up by reading the Designer’s Guide to Magento.

This article will provide a little background on structural blocks as well as a guide to creating and populating a new structural block.

Structural Blocks Defined
Structural blocks are the parent blocks of content blocks. Structural blocks serve to position content blocks within the context of a given page (or page layout) in your store. In other words, structural blocks create the visual structure for a store page. Examples of structural blocks include the header, the left column, the right column, and the content area. See below for diagrams of structural blocks and content blocks.

Creating a Structural Block
Although it can seem a bit daunting at first, creating a custom structural block only involves 3 steps and we’ve provided examples of all the code that you will need to use. Familiarity with Magento is helpful, but if you can handle copying and pasting, you should be able to succeed. If you get stuck on any of these steps, please leave a comment and we will post any needed clarifications. We will detail how to add a structural block in the footer; however, it is easy to add a structural blocks to other areas of the page by changing the location of code in the necessary .phtml file (see step 1 below).

1) Place the Structural Block
We need to instruct Magento on where to output the new structural block. Go to app/design/frontend/your_package/your_theme/template/page/ and locate the .phtml file (or files) that your template is using, typically 1column.phtml, 2columns-left.phtml, 2columns-right.phtml, or 3columns.phtml. Open the .phtml file and add the below code based on where you would like the new structural block to appear. For this guide, we have named our block “customblock”.

<div><?php echo $this->getChildHtml('customblock') ?></div>

For example, to add customblock above the footer, the code in your .phtml file should resemble the below. The new code that we added is on line 10:

<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 class="col-right sidebar"><?php echo $this->getChildHtml('right') ?></div>
            <div><?php echo $this->getChildHtml('customblock') ?></div>

2) Populate the Structural Block with Content
Now that the new structural block has been properly placed, we need to populate it with content. To do this create a new file called customblock.phtml in app/design/frontend/your_package/your_theme/template/. Once the file is created, add your content. For our purposes, we will use the below code which will display “Custom Structural Block”, however, any content that you need may be added to customblock.phtml.

<h1 style="background-color:yellow">Custom Structural Block</h1>

3) Add a New Reference Using local.xml
Now we need to add a reference so that Magento knows that the customblock structural block exists and where to locate the customblock.phtml file that we created in step 2. To do this without modifying any Magento core files, we can use our local.xml file. If you have not already created a local.xml file, create a file with this name in app/design/frontend/your_package/your_theme/layout/ and add the below code. If you are already using a local.xml file, simply integrate the code into it.

<?xml version="1.0" encoding="UTF-8"?>
        <reference name="root">
            <block type="core/text_list" name="customblock" as="customblock" translate="label">
                <label>Custom Block</label>
        <reference name="customblockreference">
            <block type="core/template" name="customblock" template="customblock.phtml" />

Now clear your cache and refresh your front end. The new custom block should appear highlighted in yellow right above the footer. Nice work! We hope you found this guide helpful.

13 Comment on “Magento — Add Custom Structural Block Reference

Leave a Reply

Your email address will not be published. Required fields are marked *