I originally wrote this for a client and I thought it might help others out there trying to do the same thing. Adding template content to Magento views ought to be really simple, but sadly due to a lack of good documentation, it is anything but.
To add a text template to a view in magento, you need to consider three aspects
- The template block itself
- The block, or layout, the template will sit in
- The layout .xml configuration
The first element is simplest, create some html, stuff it into a .phtml file and copy it to a directory within your theme, which resides (relative to the store root dir) in 'app/design/frontend/<package>/<theme>/templates'. I'm going to assume the package/theme is default/default from here forward.
You will now need to configure one or more layout xml templates (app/design/frontend/default/default/layout') to refer to your new template block. For most general purpose, globally available blocks, this will be 'page.xml'.
For example, to add a productfinder template to the three column layout, you need to edit page.xml and within the
<block type="page/html" name="root" output="toHtml" template="page/3columns.phtml">
block add the following code near the closing </block>:
<block type="core/template" name="my_product_finder" as="my_product_finder" template="templatedir/productfinder.phtml"/>
Type="core/template' refers to a Magento class Mage_Core_Block_Template. This type can be different if you want a specific type of block. But core/template is the simplest way to include some text on a page. The 'name' and 'as' attributes allow you to reference the block in your enclosing templates, e.g. 3column.phtml, or other layout .xml files. The template attribute is the relative path to the text template you want to include and is relative to the theme template root i.e. app/design/frontend/<package>/<theme>/templates.
Once you have created a layout definition for your block, including the template on a page is easy. In 3column.phtml, for example, simply put <?php $this->getChildHtml('my_product_finder') ?> and the text will be included. Remember to refresh, or clear Magento's cache first though.
One more element to consider is exclusions. If you put the above code in 3column.phtml, that text will appear on every page that uses that layout template. You may not, for example, want to include it on customer dashboard pages. In this case you will need to define a remove statement within the layout.xml for the group of pages you want to change. In this example, we need to edit customer.xml
In customer.xml (and indeed page.xml) you will see a number of elements similar to <default></default> (which applies to ALL pages), <customer_account></customer_account> (which refers to all pages with the url customer/account/), and <customer_account_edit></customer_account_edit> (which refers to all pages with the url customer/account/edit/). Including your remove declaration in the right element here allows fine grained control over which pages your blocks appear.
In the example here, we want to remove the product finder from ALL customer account pages. Therefore within the <customer_account> element we add the code
The reference name=root element ensures we are altering the root block, which is the one in which we defined our template block in page.xml. The enclosed remove call, uses the name of the block we created "mns_product_finder" to identify the block we want to remove for these pages.
That's it! All pages that exist under <customer_account> (so all of them) have this block removed.