What is the correct way/approach to modify a Magento template?

This is what you should put inside your local.xml file.

<?xml version="1.0"?>
<layout version="0.1.0">
    <catalog_product_view>
        <reference name="product.info.sharing">
            <action method="setTemplate">
                <template>catalog/product/view/test.phtml</template>
            </action>
        </reference>
    </catalog_product_view>
</layout>

Mistakes that you have done

  • You used two layout update handles: default and catalog-product-view. That is wrong. You only need one layout update handle. The right one that you should use here is catalog_product_view

  • So catalog-product-view is unknown for magento. The proper name is catalog_product_view

  • Since sharing block is already defined via catalog.xml, now you need to refer that block and then change the template by adding action setTemplate. That is what the above script does.

Hope you get the idea


I'll try to give a general answer.

How to change templates

In your theme, you can override any phtml files from the default theme or parent theme. Copy the original file to app/design/frontend/[package]/[theme]/template/[path/to/phtml] and make your changes.

If you don't have a project specific custom theme yet, for example because you just bought a theme, make sure to create one at

app/design/frontend/[original-package]/[project-name]

It will inherit from [original-package]/[default], you do not need to copy everything from default, just the files where you need to make changes.

Module specific changes

An alternative to overriding the phtml file, is to change the template path. This can usually be done in layout XML like this:

<reference name="the-block-name">
    <action method="setTemplate"><name>path/to/new/template.phtml</name></action>
</reference>

But this is intended to be used by modules who need to switch a template, not for theme specific changes. The new template should be in base/default then.

How to use local.xml / theme.xml

The local.xml file must be in the directory of the actual theme you are using, i.e.

app/design/frontend/[package]/[theme]/layout

Multiple local.xml files in the fallback hierarchy are not taken into account. The first of these that can be found, is used:

app/design/frontend/[package]/[theme]/layout/local.xml
app/design/frontend/[package]/default/layout/local.xml
app/design/frontend/base/default/layout/local.xml

(assuming default hierarchy and no custom defined hierarchy)

How to make changes

You should only have modifications in local.xml, not repeat definitions that are already in the original XML files. That also means, avoid copying XML files from the default theme to make changes directly in the files. Keep your theme's layout directory clean!

Typical elements of local.xml are <remove> to remove existing blocks entirely, <action method="unsetChild"> and <action method="append"> to move a block from one parent to another, or calling any other methods on existing blocks to modify their behaviour.

Magento 1.9

Starting with Magento 1.9, best practise is actually to not use layout/local.xml for these changes, but etc/theme.xml

In short, you can add a layout update in app/design/frontend/yourpackage/etc/theme.xml. The advantage is that you have control over the load order of your layout updates. Before Magento 1.9 local.xml was always loaded last, and it was impossible to have layout directives be executed after it.

I’m not using local.xml any more for project-specific theme modifications. I think local.xml is just used for backward compatibility reasons (in 1.9 and above) as there is no point in using it any more. Local.xml is also eliminated in Magento 2 (https://github.com/magento/magento2/issues/1037).

Source: https://erfanimani.com/dont-use-local-xml/