Add New Reference in Magento
28 Comments 5th MAR 2009 | Posted by Tomislav Bilic 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 below 2 columns, but above the footer. In this case, our updated file could look like this:
<!-- start middle -->
<div class="middle-container">
<div class="middle col-2-right-layout">< ?php getChildHtml('breadcrumbs') ?>
<!-- start center -->
<div id="main" class="col-main"><!-- start global messages -->
< ?php getChildHtml('global_messages') ?>
<!-- end global messages -->
<!-- start content -->
< ?php getChildHtml('content') ?>
<!-- end content --></div>
<!-- end center -->
<!-- start right -->
<div class="col-right side-col">< ?php getChildHtml('right') ?></div>
<!-- end right --></div>
<div>< ?php getChildHtml('newreference') ?></div>
</div>
<!-- end middle -->
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. We will put new products block there as an example. Go to appropriate layout XML file and add this block to appropriate place.
<reference name="newreference"> <block type="catalog/product_new" name="home.product.new" template="catalog/product/new.phtml" /> </reference>
That’s it. I hope it will help someone 
If you like what you read, please share it.
To post code in comments, place your code inside [code] and [/code] tags.
There are 28 comments (Add Yours +)
Meet The Inchooers, the funny bunch of magento developers.
March 5th, 2009 at 19:50
Good post!
Check it, on step 3:
–> the name must be newreference, according with you layout.
Greetings!
March 5th, 2009 at 20:23
Thanks Pablo. Good blog you have. I corrected my post and updated Step 3. Have a good day.
March 6th, 2009 at 17:40
Thanks to you, your posts are useful and effective.
March 6th, 2009 at 23:00
Step3: “..Go to appropriate layout XML file and add this block..”
Thank you Tomislav, but what would be an “appropiate” XML temlate file, in this case?
Could you please explain it?
I came here from this post: http://www.magentocommerce.com/boards/viewthread/8085/, and still can’t grasp the logic.
What would be really great, is to understand how can I conclude that contents of the “” from the “page.xml”, is defined precisely in “catalog.xml” file and nowhere else?
ps
Nice blog, keep it going)
March 6th, 2009 at 23:04
missing:
“…how can I conclude that contents of the “left” block (which is left column in a template) from the “page.xml”…”
March 7th, 2009 at 9:23
Hello Janis,
As I wrote at the beginning of the article, I advise you to read Designers Guide to Magento. Most of your questions are explained there. I hope it helps.
Let me know if you have questions after you analyze the guide.
March 10th, 2009 at 13:04
Thank you very much!
Good post!
March 14th, 2009 at 14:00
Thanks…
But. How to create block over header?
April 1st, 2009 at 14:53
i`d like to submit your rss just for magento category, how can i do that?
May 16th, 2009 at 0:04
how can I set up this new block to have different static blocks in it depending upon what page it is on.
May 22nd, 2009 at 13:44
I use Free CMS, it’s very useful. You can see the demo here: http://demo.hello-magento.com/freecms/furniture.html
June 1st, 2009 at 5:45
How do i add custom block inside template file: http://www.magentocommerce.com/boards/viewthread/43897/
Thanks.
July 15th, 2009 at 15:33
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. We will put new products block there as an example. Go to appropriate layout XML file and add this block to appropriate place.
i have put this on catalog.xml ok?
But i don’t know the line, i think that is:
catalog_seo_searchterm_popular>
page/1column.phtml
July 20th, 2009 at 17:55
Hey Thanks! This put me on the right track quickly. Spent a while with wiki and still couldn’t see what was up… Thanks for the quick step-by-step. Keep up the good work!
August 20th, 2009 at 21:30
Thanks ! your posts are useful and effective .
I create such type of block .
But …..how we add multiple static images in created structural block ?
September 9th, 2009 at 21:04
What about creating a new content block. How is it defined? Can I add a content block as a Custom Layout Update as I only need it included on one page?
September 16th, 2009 at 13:04
Thanks. You have sloved my problem………
December 22nd, 2009 at 1:16
Good stuff for real! Thanks.
March 8th, 2010 at 20:44
Does not work for me….please any one help me?
April 5th, 2010 at 21:43
I support your efforts, but the tutorial lacks vital details. I honestly cannot find the locations of the XML file in question.
May 5th, 2010 at 16:21
Thanks, It sure helped!
May 12th, 2010 at 20:35
I’ve got to agree with the previous posters.
Why go to the bother of putting together this – potentially – great post, without the crucial finishing stages?
Anyone want to finish it off? Please….
May 22nd, 2010 at 13:42
I’m the same … this is a great post … and takes me 90% of the way there, but the extra 10% would polish it off for me – and let me JUST read this and not have to try and cross-match to relevant places in the rather large guides elsewhere.
Tomislav – could you take 15 minutes out and just add in details such as the location of the XML file, and so on.
Thanks so much in advance
Mark
May 26th, 2010 at 14:55
Wel done! Works!
Thanks!!!!
June 16th, 2010 at 1:41
Is there a way to create a reference for a static block?
For example you may want to utilize a block file that requires actions to be set such as the following:
http://www.url.com/feed/
5
By default the feedreader is setup to reference the right or left sidebar:
however I want to call block within a static block:
{{block type=’feedreader/sidebar’ name=’left.feedreader’ template=’feedreader/sidebar.phtml’}}
Yet the bock is unable to function properly because the actions are not set:
http://www.url.com/feed/
5
July 18th, 2010 at 18:01
Your post is just awesome.
But however,
If the newreference block has to appear only if it has content inside it, otherwise, it should not be populated.
Actually, I want to populate this block on CMS and checkout pages, and not on the PRODUCT PAGE.
Any kind of help would be greatly appreciated.
Thank You
August 3rd, 2010 at 13:59
Ok, here is the FINAL step for all of you who (like me) have struggled with locating ‘the appropriate layout XML file’.
1. Within your Magento installation, open app/design/frontend/(interface)/(theme)/layout/page.xml
2. Scroll down until you see the custom page layout handles section.
3. Select the page layout you want your new structural block to appear in (e.g. All One-Column Layout Pages, etc) – this is what the author means by ‘selecting the appropriate layout XML file’.
4. Copy and paste the XML from Step 3 into the ‘appropriate’ page section. Note at this stage it may be worth changing the attribute template=”catalog/product/new.phtml” to template=”catalog/product/newreference.phtml” just so you can see it working when you have completed the following stages.
5. Save the amended page.xml.
6. Make a copy of app/design/frontend/(interface)/(theme)/template/catalog/product/new.phtml and rename it newreference.phtml.
7. Open newreference.phtml, delete everything in it and add some basic HTML markup (e.g. Hello World).
8. Save newreference.phtml and refresh your store page. You should see Hello World appear just above the footer.
9. Populate newreference.phtml with whatever content/code you like!
It works for me and hopefully will help all of you out there who have struggled at the last step.
August 5th, 2010 at 10:32
I’m stuck, does this work on Magento 1.4.1.0? Looks like the syntax has changed, for example block has to be closed with [code][/code] instead of
../>Maybe someone could upload actual modified page.xml because I don’t know where to paste that step3 code. I tried this but it doesn’t work:
All Two-Column Layout Pages (Right Column)
page/2columns-right.phtml
<!-- Mark root page block that template is applied -->
1