Magento Extension Needs to Override a Template

Question

I'm working on a simple extension for my store and it needs to override a template file.

The template in question is used to generate each line item in the list of items in an order. To see what I'm talking about, you can go to My Account->My Orders, select an order, and then scroll down to see the table under "Items Ordered." The default template file I'm trying to replace is sales/order/items/renderer/default.phtml.

I have successfully set up the extension to use its own layout.xml file. I can, for example, turn off various blocks on the page. My code for changing the template, however, isn't working. I suspect that my reference name(s) is(are) incorrect, but I don't know for sure.

Here is what I have so far:

<?xml version="1.0"?>
<layout version="0.1.0">
    <sales_order_view>
        <reference name="my.account.wrapper">
            <reference name="sales.order.view">
                <reference name="order.items">
                    <reference name="sales.order.item.renderer.default">
                        <action method="setTemplate">
                            <template>groupname_extensionname/sales/order/items/renderer/default.phtml</template>
                        </action>
                    </reference>
                </reference>
            </reference>
        </reference>
    </sales_order_view>
</layout>

Could anyone provide the corrections I need in my xml (and elsewhere if necessary)? Thanks in advance.

Edit:

Here is my modified version of Ben's XML that worked (he only missed an argument that was easy to add):

<?xml version="1.0"?>
<layout version="0.1.0">
    <sales_order_view>
        <reference name="order_items">
            <action method="addItemRender">
                <arg1>default</arg1>
                <arg2>sales/order_item_renderer_default</arg2>
                <arg3>groupname_extensionname/sales/order/items/renderer/default.phtml</arg3>
            </action>
        </reference>
    </sales_order_view>
</layout>

Edit:

I found you can copy the default xml tags for the arguments, so instead of arg1, arg2, arg3 you can have type, block, template.

<?xml version="1.0"?>
<layout version="0.1.0">
    <sales_order_view>
        <reference name="order_items">
            <action method="addItemRender">
                <type>default</type>
                <block>sales/order_item_renderer_default</block>
                <template>groupname_extensionname/sales/order/items/renderer/default.phtml</template>
            </action>
        </reference>
    </sales_order_view>
</layout>

Answer 1

Heh, one nice thing about references is that they operate through that global space of the layout object, so you needn't do any nesting. Kudos for working this through to layout xml; it's powerful!

What you want to do, I think, is replace the default item renderer which is being set in the sales module's LXML file (see sales.xml). These are added to the block class Mage_Sales_Block_Order_Items (or sales/order_items in class group notation) via the addItemRender() method, which comes from Mage_Sales_Block_Items_Abstract. You need to replace the renderer stored in the default key of the _itemRenderers array, and you can do that simply by doing the following:

<sales_order_view>
    <reference name="order_items">
        <action method="addItemRender">
            <arg1>default</arg1>
            <arg2>groupname_extensionname/sales/order/items/renderer/default.phtml</arg2>
        </action>
    </reference>
</sales_order_view>

Let me know if this doesn't do the trick, because it shouldn't take much more beyond this.

Answer 2

Layout <references/> don't work like that. The outer tags (<sales_order_view/>) are called handles, and then the first level of tags inside a handle is a command that either creates, or gets a reference to a block object, and then the layer inside of that is used for calling block methods via an <action/> node. (the two exceptions are <remove/> and <update>, which are scanned for separately from the block creation process, and can be placed anywhere).

So your layout xml update will look like this.

<sales_order_view>
    <reference name="name.of.block.in.layout">
        <action method="setTemplate">                
            <template>groupname_extensionname/sales/order/items/renderer/default.phtml</template>
        </action>
    </reference>
</sales_order_view>

Some other advice to help you along the way

1. You'll need to replace 'name.of.block.in.layout' with the name that Magento gives the block that has the sales/order/items/renderer/default.phtml template

2. Make sure you're adding your layout xml to the ADMIN layout.

3. Make sure you use <depends/> in app/etc/modules/Foo_Bar.xml to ensure yoru module loads after the Mage_Adminhtml module.

4. It may be possible that Magento is generating the block you're looking for in PHP code, which means you won't be able to use the layout the way you're using it

5. It may be simpler to look into seeing a different default admin theme for Magento (or using the find theme that ships with modern versions of Magento and is the default admin theme), and just replacing the phtml file via template hierarchies.

(Magento layouts are pretty complicated, it took me a small book to explain them.)