Add a New Reference in Magento

newreference

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”.

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.

89
Top

Care to rate this post?

Author

Tomislav is a founder and CEO at Inchoo. Enjoys traveling, traditional cuisine (from most cultures), good wine and strong rakija.

Other posts from this author

Discussion 89 Comments

1 2
Add Comment
  1. Man you are a life safer you know that..

    When ever we are stack in something we finish always in a post you have made.

    I understand so many things today with your post.

    thanks a lot…

  2. How can i add new block inside content?

    i tried to add new ref block inside the content ref but it shows on the top of the page not where i want.

    any help would be appreciated.

  3. guy

    thankyou .. finally, FINALLY ! i understand reference / blocks / layout / xml / templates .. suddenly i see it , and i thankyou :)

  4. Amit

    thanks a lot for sharing .. i also got it finally. No issues with 1.6 as earlier stated by me .

  5. Its almost exactly what I need. But I dont know how can I create a custom method to call inside phtml like $this->customMethod();

  6. This is the best tutorial on for adding structural blocks for Magento

    Big Thumbs up!

  7. Duncan

    If I wanted to add a static block via a widget to a custom reference block, how might I go about doing that?

  8. The php in the template where you want to output the block needs to be:
    echo $this->getChildHtml(‘newreference’)
    instead of
    getChildHtml(‘newreference’)
    which throws an error

  9. Mike

    Sorry but where is the appropriate xml file in step 3? There is no: app/design/frontend/default/yourtheme/layout/local.xml

  10. @Mike feel free to create local.xml in app/design/frontend/default/yourtheme/layout/

    Take a look here: http://inchoo.net/ecommerce/magento/using-local-xml-for-overriding-or-updating-xml-structure/

    Cheers!

  11. Bob

    “Go to appropriate layout XML file and add this block to appropriate place.”

    First of all what is the “appropriate” file? Is this the local.xml?

    And why is it added there, seems a bit double to me, I already created a block in my page.xml, why should I add another block reference in another file…?

  12. munter

    hi,
    thank you for your great post!

    i use version 1.7.0.0 and modify the step 2 to

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

    have a nice time!

  13. Really many thanks to share this throubleshooting!

  14. squizeers

    Followed the instructions and worked on the category pages but not in other pages. On other pages it gives an error

    Fatal error: Call to a member function getMetaTitle() on a non-object in /home/sabatest/public_html/app/code/core/Mage/Catalog/Block/Category/View.php on line 44
  15. Thank you very much.
    You really saved my a good bunch of research hours.

    For all those who had problems, this is what I did:

    - Step 1: go to layout/page.xml
    look up for this code:

    All Pages

    then add you new structural block:

    - Step 2:
    Call the block from a layout page, for instance, 2columns-right.phtml, with this code:

    getChildHtml(‘right’) ?>

    - Step 3:
    Populate the block
    Go to catalog.xml and add:

    [ Add your blocks here]

    HOPE THAT WORKS GOOD FOR YOU AS WELL ;)

  16. Thank you Ivan Galambos for updating this post. Everyone, hope that new longer post will make the topic more clear.

  17. I did exactly as the step-by-step, but nothing happens in my store. What could it be? Have I’m reviewing the page.xml and phtml several time.

  18. Rupert

    I have done this around 3 times now, cleared magento cache (even though its not turned on) as well as browser cache and it does not work. am on magento 1.7

    Please help, your tutorial seems straight forward, just does not work?

  19. Alpesh

    You are a genus !! Fantastic tutorial…. Thank you very very much

  20. Glauco

    Yep, same as a few other people here: this doesn’t seem to work in Magento 1.7. I followed everything to the letter and refreshed cache, nothing shows up. I have already tried a bunch of other tutorials for adding custom blocks and after hours of utter frustration I can’t get even a simple “Hello world” to appear where I need it to. What the heck? Can someone confirm if they have managed to get this to work in Magento 1.7 and how they did it? Thanks!

  21. Muthu

    Really Hates off to this blog. Whatever help i need on magento, the first site i prefer to search is your blog..

    Thanks!

  22. exactly what I need Thank you
    best tutorial

  23. Very nice tutorial, thanks man. I was looking for a long time for a instruction like this.

    I will use this to create a new reference underneath my menu to point out our unique selling points!

    Thanks Inchoo!

  24. Carolina

    It woks in magento 1.7 =), but only if you do step 4!

  25. Madzack

    I want to add a block in content block. Is it possible? I want to do it so that i can show right/left bar below the toolbar/pager. Please anybody help.

  26. chris

    Stuck on step 2.
    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).

    Where is the default handle ? nothing about default in page.xml ??

  27. abraham

    add new structural block in product page???

  28. Hello,

    Very good post, clear and easy to follow.

    I have one question, is it posible to make this block visible from the back-end??? I want to put slider in this block (custom one) and then load it via widget, so that the client could update images via back-end.

    Thanks a lot for the great post!!!

    Regards,
    Artur

  29. Thank you, Very good post, clear and easy

  30. Hi guys,

    Great tip, however I wonder if there isn’t another way to do this using the static blocks in admin and then callout them?
    To make it dynamical it should be better using static blocks.

  31. suhas

    Good Tutorial

  32. siju

    To create a structural block in product listing page, do this:

    in local.xml,

    Custom Reference

    And, in catalog/product/list.phtml,

    getChildHtml(‘newreference’) ?>

  33. siju

    To create a structural block in product listing page, do this:

    in local.xml,

    <catalog_category_layered>
            <reference name="product_list">
               <block type="core/text_list" name="newreference" as="newreference" translate="label">
                    <label>Custom Reference</label>
                </block>
            </reference>
        </catalog_category_layered>

    And, in catalog/product/list.phtml,

      <?php echo $this->getChildHtml('newreference') ?>
  34. i need that this block only appear on home page of my shop, is it possible?

  35. Boomer

    How can one create a home page only block eg for a silder above the main class?

  36. Thanks, this is helpful.

  37. João G.

    Hi, thanks for the tutorial. I have a doubt: I’ve created a page “bestsellers.php” in the path “catalog/product/bestsellers.phtml” where I get and show the bestsellers collection. I put the line

    &lt;block type=&quot;core/text_list&quot; name=&quot;product_bestsellers&quot; as=&quot;product_bestsellers&quot; /&gt;

    in page.xml and I have a custom template page “home.phtml” in “page/home.phtml” which is my homepage. I put the line

    &lt;reference name=&quot;product_bestsellers&quot;&gt;
    			&lt;block type=&quot;catalog/product&quot; name=&quot;product_bestsellers_block&quot; template=&quot;catalog/product/bestsellers.phtml&quot;/&gt;
    		&lt;/reference&gt;

    into page.xml and in home.phtml I have the callout

    &lt;?php echo $this-&gt;getChildHtml('product_bestsellers') ?&gt;

    . The point is that the content of bestsellers.phtml hasn’t been displayed. What is wrong?

    Thanks.

  38. Paragraph writing is also a fun, if you know after that you can write
    or else it is complex to write.

  39. Joel

    Thanks for explaining this concept of structural blocks. It is not documented very well in other tutorials!

1 2

Add Your Comment

Please wrap all source codes with [code][/code] tags.
Top